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:

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

Cache not working — tasks re-run when they should be cached

Symptoms: A task runs even though nothing relevant has changed. Cache hit percentage is lower than expected.

Step 1: Verify the task is cacheable.

nx show project <project-name> --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:

// 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:

nx graph --file=output.json

Step 3: Reset the local cache.

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.

Project not found in graph

Symptoms: nx run <project>:<target> 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:

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:

// nx.json
{
  "workspaceLayout": {
    "appsDir": "applications",
    "libsDir": "packages"
  }
}

Check 4: Reset and re-analyse.

nx reset
nx graph

Tasks taking too long

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:

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.

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:

npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="build"

nx graph shows wrong dependencies

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.

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:

// 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:

{
  "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.

Nx daemon issues

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.

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.

nx daemon

This prints the path to the daemon log file. Open the file to inspect errors.

Disable the daemon if needed.

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.

Out of memory errors

Symptoms: Node.js throws JavaScript heap out of memory, or the OS kills the process during nx run-many.

Reduce parallel task count.

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.

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:

nx affected -t lint
nx affected -t test
nx affected -t build

Profile to find the culprit.

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

GitHub Issues

File a bug report or feature request. Include the output of nx report and a minimal reproduction when possible.

Nx Community

Join the Nx Discord server for community support, announcements, and discussion.