> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nrwl/nx/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> Solutions to common Nx issues: cache misses, project graph problems, daemon errors, memory limits, and how to gather diagnostic information.
This page covers the most common issues encountered in Nx workspaces and how to resolve them.
## Diagnostic commands
Before investigating a specific issue, gather workspace information:
```shell theme={null}
nx report
```
`nx report` prints:
* Nx version and all installed `@nx/*` package versions
* Node.js version and OS/architecture
* Detected package manager
* List of installed Nx plugins
Include this output when filing a GitHub issue or asking for help.
## Common issues
**Symptoms:** A task runs even though nothing relevant has changed. Cache hit percentage is lower than expected.
**Step 1: Verify the task is cacheable.**
```shell theme={null}
nx show project --web
```
Look for the "Cacheable" label on the target. If it is missing, add `"cache": true` to the target in `project.json` or in `nx.json` under `targetDefaults`:
```json theme={null}
// nx.json
{
"targetDefaults": {
"build": {
"cache": true
}
}
}
```
**Step 2: Check `inputs` configuration.**
If a file that changes the output is not listed in `inputs`, Nx will not detect the change and may serve a stale cache entry. If an output file is written outside the declared `outputs`, it may inadvertently modify an input on the next run.
Inspect which files belong to a project's inputs:
```shell theme={null}
nx graph --file=output.json
```
**Step 3: Reset the local cache.**
```shell theme={null}
nx reset
```
This clears the local cache directory and stops the Nx daemon. Re-run the task to get a fresh result.
**Step 4: Use Nx Cloud's comparison tool.**
If connected to Nx Cloud, click the run details link printed in the terminal. Filter tasks by "cache miss", open the task details, and click **Compare to similar tasks** to see a diff of hash inputs between two runs.
**Symptoms:** `nx run :` reports that the project does not exist, or `nx graph` does not show the project.
**Check 1: Verify the project name.**
The project name is the `name` field in `project.json`, or the `name` field in `package.json` when using package-based projects. Run:
```shell theme={null}
nx show projects
```
to list all projects Nx has discovered.
**Check 2: Confirm the project file exists.**
Nx discovers projects by locating `project.json` or `package.json` files. Ensure at least one exists in the project directory.
**Check 3: Check `workspaceLayout` in `nx.json`.**
If your apps or libraries are not in the default `apps/` and `libs/` directories, configure:
```json theme={null}
// nx.json
{
"workspaceLayout": {
"appsDir": "applications",
"libsDir": "packages"
}
}
```
**Check 4: Reset and re-analyse.**
```shell theme={null}
nx reset
nx graph
```
**Symptoms:** Individual tasks or the overall pipeline takes unexpectedly long to complete.
**Check 1: Review task pipeline configuration.**
An overly strict `dependsOn` chain — for example, `test` depending on `build` unnecessarily — forces sequential execution. Review `targetDefaults` in `nx.json` and remove unnecessary dependencies.
**Check 2: Adjust parallelism.**
By default Nx runs tasks in parallel up to the number of available CPU cores. Override with:
```shell theme={null}
nx run-many -t build --parallel=4
```
Reduce this value if tasks compete for memory; increase it on machines with more cores.
**Check 3: Profile the run.**
```shell theme={null}
NX_PROFILE=profile.json nx run-many -t build
```
Open `profile.json` in the Chrome DevTools **Performance** tab to see a flamegraph of when each task ran and which tasks were waiting on others.
**Check 4: Enable Nx Agents on CI.**
For CI bottlenecks, distribute tasks across multiple machines:
```shell theme={null}
npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="build"
```
**Symptoms:** The project graph shows a dependency that doesn't exist, is missing a real dependency, or shows an incorrect direction.
**Step 1: Force re-analysis.**
```shell theme={null}
nx reset
nx graph
```
**Step 2: Check `tsconfig.json` path aliases.**
Nx uses TypeScript path mappings to detect imports between projects. If `tsconfig.base.json` does not list a path alias for a project, imports to that project may not be detected:
```json theme={null}
// tsconfig.base.json
{
"compilerOptions": {
"paths": {
"@myorg/shared": ["libs/shared/src/index.ts"]
}
}
}
```
**Step 3: Check for dynamic imports.**
Nx performs static analysis. Dynamic `require()` calls with variable paths cannot be resolved. Use explicit import strings or add explicit `implicitDependencies` in `project.json`:
```json theme={null}
{
"name": "my-app",
"implicitDependencies": ["shared-lib"]
}
```
**Step 4: Review `.nxignore`.**
Files matching patterns in `.nxignore` are excluded from analysis. Ensure project source directories are not inadvertently ignored.
**Symptoms:** Commands are slow to start, the daemon logs show errors, or Nx reports it cannot connect to the daemon.
The Nx daemon is a background process that caches the project graph in memory and watches for file changes. It is enabled automatically on local machines and disabled by default in CI.
**Resolution: Reset the daemon.**
```shell theme={null}
nx reset
```
This stops the daemon, clears its socket, and purges the local cache. The daemon restarts automatically on the next Nx command.
**View daemon logs.**
```shell theme={null}
nx daemon
```
This prints the path to the daemon log file. Open the file to inspect errors.
**Disable the daemon if needed.**
```shell theme={null}
NX_DAEMON=false nx build my-app
```
Or set `useDaemonProcess: false` in the runner options in `nx.json` to disable it permanently.
The daemon is automatically disabled in Docker containers and CI environments. If you need it in a long-running container, set `ENV NX_DAEMON=true` in your Dockerfile.
**Symptoms:** Node.js throws `JavaScript heap out of memory`, or the OS kills the process during `nx run-many`.
**Reduce parallel task count.**
```shell theme={null}
nx run-many -t build --max-parallel=2
```
Lowering `--max-parallel` (or `--parallel`) reduces the number of tasks running simultaneously, which reduces peak memory usage.
**Increase Node.js heap size.**
```shell theme={null}
NODE_OPTIONS=--max-old-space-size=8192 nx run-many -t build
```
**Split affected by target.**
Run targets in sequence rather than in parallel across all targets:
```shell theme={null}
nx affected -t lint
nx affected -t test
nx affected -t build
```
**Profile to find the culprit.**
```shell theme={null}
NX_PERF_LOGGING=true NX_DAEMON=false nx build my-app
```
This prints detailed timing for each phase of Nx startup and task execution, which can reveal plugins with excessive memory usage.
## Getting help
File a bug report or feature request. Include the output of `nx report` and a minimal reproduction when possible.
Join the Nx Discord server for community support, announcements, and discussion.