How does Nx compute a task hash?

Before Nx runs a task, it computes a hash that summarizes everything the task's result is supposed to depend on. If a cache entry with that hash already exists, locally or in a remote cache, Nx restores the recorded outputs and terminal logs instead of executing the task. The hash is a claim that identical inputs produce identical results, so a hit is only as trustworthy as the input definition behind it.

The hash combines several components:

  • File inputs: the project's own files, filtered through the inputs (or named inputs) configured for the target.
  • Dependency inputs: entries prefixed with ^ pull in files from the projects this project depends on in the project graph, so a change upstream propagates downstream.
  • External dependencies: resolved versions of third-party packages the project uses, taken from the lockfile rather than from version ranges in package.json.
  • Runtime inputs: the output of a command Nx runs at hash time, such as a tool version check.
  • Environment variable inputs: the values of variables you explicitly declare.
  • Target configuration and arguments: the executor or command, its options, and flags passed on the command line.
  • Workspace-level configuration: shared files such as nx.json and root-level configuration that affect every project.

Changing any single component changes the final hash. A miss is never random. Some specific input differed, and you can find out which one.

The reverse does not hold. A task whose outputs differ across runs with the same inputs is unsafe to cache, even when the hashes match. Examples include embedding timestamps, reading undeclared environment variables, or depending on network responses. In these cases a cache hit replays a result that may not be correct.

Task hash inputs (change any one -> different hash)
+--------------------------------------+
| File inputs (target inputs filter)   |--+
+--------------------------------------+  |
| Dependency inputs (^ upstream files) |--+
+--------------------------------------+  |
| External deps (lockfile versions)    |--+
+--------------------------------------+  |    +----------------------+
| Runtime inputs (command output)      |--+--->| Task hash            |
+--------------------------------------+  |    +----------+-----------+
| Env var inputs (declared vars only)  |--+               |
+--------------------------------------+  |               v
| Target config + CLI arguments        |--+    +----------------------+
+--------------------------------------+  |    | Cache lookup         |
| Workspace config (nx.json, root)     |--+    | local or remote      |
+--------------------------------------+       +---+-------------+----+
                                                   |             |
+--------------------------------------+       hit |             | miss
| Nondeterministic task: same hash,    |           v             v
| different output (timestamps,        |   +---------------+ +---------------+
| undeclared env vars, network).       |   | restore saved | | run the task, |
| A hit may replay a wrong result.     |   | outputs, logs | | store result  |
+--------------------------------------+   +---------------+ +---------------+

Seven input components combine into a single Nx task hash that keys a local or remote cache lookup, so a change to any one component causes a miss, while a matching hash does not make a nondeterministic task safe to cache.

Who should use this debugging approach?

This guide is for engineers who work in an Nx workspace that has caching enabled, and who need to find out why a task did not hit the cache when they expected it to. In practice that usually means one of these groups:

  • Platform and CI owners who are responsible for pipeline duration and compute spend, and who have to explain why a pipeline ran far longer than usual.
  • Monorepo maintainers who edit nx.json, targetDefaults, named inputs or plugin configuration, and who need to confirm that a change did not quietly widen or narrow what gets hashed.
  • Application engineers who see a full rebuild after a small change, or a CI miss on a commit that hit locally, and want a method they can repeat instead of guessing.

The approach pays off most in large workspaces with deep dependency graphs, shared root configuration, and a remote cache shared between developers and CI, because those are the conditions where one misconfigured input affects many tasks. In a small repository where a full build finishes quickly, broad inputs and the occasional miss may cost less than the time you would spend tuning them.

Where do task inputs come from, and how do you see the effective ones?

Before you can explain why a hash changed, you need to know which inputs Nx actually used. That is often not what any single config file says, because several layers contribute to the final definition of a target.

The layers that produce a target's inputs

Source Where it lives Typical role
Plugin-inferred inputs Generated by plugins from tool config files Baseline inputs for targets the plugin creates
targetDefaults nx.json Workspace-wide inputs per target name or executor
Target-level inputs project.json or package.json Per-project override for one target
namedInputs nx.json, can be redefined per project Reusable sets such as default and production

Later layers generally take precedence over earlier ones. For inputs, an explicit array on a target replaces the inherited array rather than appending to it. This is a common source of surprise: you add one file glob to a target and lose everything targetDefaults was supplying. Named inputs make this harder to see, because production in one project can resolve to different globs than production in another if a project redefines it. If no layer specifies inputs, Nx falls back to default for the project's own files and ^default for its dependencies.

Inspect the resolved configuration

Run nx show project <name>, either with --web for the graph view or with --json for output you can diff. Either form shows each target after merging, and that merged result is what the hasher uses. Debug against this output, not against the files you edited.

Plugin defaults and inference rules change between Nx versions. Check the documentation for the version you have installed, and re-run nx show project after every upgrade.

nx show project my-app --json > /tmp/my-app.resolved.json

jq '.targets.build.inputs' /tmp/my-app.resolved.json
jq '.namedInputs.production' /tmp/my-app.resolved.json

jq '.targets.build.inputs' /tmp/my-app.resolved.json > /tmp/inputs.before.json

nx show project my-app --json | jq '.targets.build.inputs' > /tmp/inputs.after.json
diff -u /tmp/inputs.before.json /tmp/inputs.after.json

Uses nx show project --json with jq to extract a target's resolved inputs and the project's named inputs, then diffs the merged result from before and after a config change to catch an explicit inputs array replacing inherited inputs.

How does hash-detail diffing work?

The method depends on one property of the hasher: the final task hash is a deterministic function of its components. Each component (the command, each project's file hashes, each runtime value, each declared environment variable, the external dependency hashes) is hashed on its own, and those results are combined into the single task hash. The hash details for a task are that list of per-component values.

Because the combination is deterministic, two runs whose task hashes differ must have at least one component whose value differs. Comparing the final hashes only tells you that something changed. Comparing the component lists tells you which part changed. The process has three steps:

  1. Capture the hash details for the same task from a run that hit and a run that missed.
  2. Compare component by component. Most components will match. The few that differ localize the cause to a category: a file under a particular project, a dependency's files, a runtime command's output, an environment variable, or the lockfile.
  3. Map the changed component back to configuration. Use the resolved project definition from nx show project to find which input, named input or ^ entry brought that component into the hash, and which config layer defined it.

The changed component identifies what differed. The resolved configuration explains why that value was part of the hash at all. You usually need both to decide whether to fix the environment, for example by pinning a variable, or to fix the input definition, for example by excluding an artifact directory.

How do you debug an Nx cache miss by diffing hash details?

This workflow is for the platform and backend engineers who own CI times and get asked why a pipeline that should take minutes took an hour. You need two runs of the same task: one that hit the cache and one that missed, or the same commit run on two machines. One run alone tells you the hash. It doesn't tell you what changed.

From each run, capture the per-task hash details. These list every component Nx fed into the hash: the command, project and dependency file hashes, runtime values, environment variables, and external dependency versions. How you get them depends on your Nx version and tooling. It may be CLI output, metadata written after a run, or an editor integration, so confirm the method for your installed version before you rely on it.

Normalize both captures before you diff them. Sort keys, and strip anything that differs between machines for harmless reasons. If you skip this, the diff fills up with noise and hides the one change that matters.

Then diff one component at a time. Start broad: did the runtime or environment section change, or only the file hashes? Narrow down from there until you find a single input that differs. That input is your root cause.

--skip-nx-cache and deleting the cache directory are diagnostic tools, not fixes. If a fresh run produces correct output and a replayed one doesn't, you've confirmed that replay is the problem. If you rely on these as a workaround, every run pays full CI time, and the misconfigured input is still there for the next person to find.

#!/usr/bin/env bash
set -euo pipefail

hit="$1"
miss="$2"

NOISE_FILTER="${NOISE_FILTER:-.}"

norm() {
  jq -S --arg k "$2" "($NOISE_FILTER) | .[\$k] // null" "$1"
}

components=$(jq -r -s '(.[0] + .[1]) | keys[]' "$hit" "$miss")

for c in $components; do
  if cmp -s <(norm "$hit" "$c") <(norm "$miss" "$c"); then
    echo "same:    $c"
  else
    echo "CHANGED: $c"
    diff -u <(norm "$hit" "$c") <(norm "$miss" "$c") || true
  fi
done

A script that normalizes two captured hash-details files with jq and diffs them one component at a time, so a cache miss narrows down to the input that changed. A comment at the end shows using --skip-nx-cache only to confirm the diagnosis.

Which file inputs most often cause unexpected misses?

Once you have the diff, the changed entry is usually one of a small set of file-input mistakes.

Build artifacts inside {projectRoot}. Default inputs typically cover everything under the project root. If a build writes to {projectRoot}/dist, or a code generator emits files there, and those paths aren't gitignored, the next run hashes the previous run's output. You get a miss after every build, even on a clean tree.

Outputs that overlap inputs. This is the same problem in a stricter form. When a task's outputs glob matches files its inputs also match, a cache replay restores those files and changes the inputs for the next run.

Untracked versus ignored files. Nx hashes the working tree, not the last commit, so a stray untracked file on a laptop changes the hash. Gitignored files are excluded from hashing. A gitignored file that actually affects the build produces stale hits rather than misses.

Spec files in production inputs. If build uses the full project glob, editing a test invalidates the build cache.

Broad root files. When tsconfig.base.json or the root package.json sits in a named input that every project uses, touching it misses everywhere.

Culprit Symptom Typical fix
Artifacts in project root Miss on every rerun Move outputs out, or gitignore them
Spec files in build inputs Test edit rebuilds Exclude specs from production inputs
Shared root config Workspace-wide miss Split config per project

Splitting root config into per-project files limits how many projects a change affects. The cost is more files to maintain, and settings duplicated across them will drift unless something keeps them consistent.

Why does a task miss in CI but hit locally?

A local hit followed by a CI miss means some input differs between the two machines. The source files are usually the same, so look at the inputs that come from the environment around them.

Lockfile changes. Nx derives external dependency hashes from the lockfile, and that hashing is coarse. Bumping one unrelated package can change hashes for tasks that never import it. You can tune externalDependencies to reduce this, but if you narrow it too far, a real dependency upgrade can reuse stale output without any warning.

Environment variable inputs. An env input hashes the variable's value on each runner. CI often sets values that your laptop doesn't, such as build numbers, runner names or temp paths.

Runtime inputs. A runtime input hashes a command's output. If that output includes a full tool version string, a hostname or the date, the hash changes on every machine or every day.

Platform differences. Git can convert line endings on checkout, so the same file has different bytes on Windows and Linux. OS-dependent tools may also print different output.

Cause Why the hash differs Fix
Lockfile bump Coarse external dependency hashing Accept it, or narrow inputs carefully
Env input Value is set per runner Pin or normalize the value
Runtime input Command output varies Emit only stable fields
Line endings Bytes differ after checkout Enforce line endings in git attributes

Env and runtime inputs keep caching correct only when their values are pinned or normalized. Without that, a cache hit on another machine is unlikely.

Remote cache misses are a separate case. If the hashes match locally and in CI but CI still gets no remote hit, the input hashing is working. Check the cache configuration, the read and write permissions for each environment, and whether the artifact was uploaded and is still retained.

{
  "targetDefaults": {
    "build": {
      "cache": true,
      "inputs": [
        "production",
        "^production",
        { "env": "NODE_ENV" },
        { "runtime": "node -v" },
        { "externalDependencies": ["vite", "typescript"] }
      ]
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*"],
    "production": ["default", "!{projectRoot}/**/*.spec.ts"]
  }
}

An nx.json build target that hashes a pinned env var, a stable runtime command and an explicit externalDependencies list, instead of per-runner values such as build numbers or dates.

Why did a project I didn't touch miss the cache?

When a task's inputs include ^production (or any named input with a ^ prefix), Nx hashes the matching files from every project the task depends on, not only from the project itself. This applies transitively through the dependency graph. If an API service imports a shared config library, and that library imports a logging library, a whitespace change in logging changes the hash of the API's build task. You never touched the API, but Nx treats its inputs as changed, and it is correct to do so: the compiled output could differ.

To find the cause, run nx graph --focus=<project> and look at the upstream dependencies of the project that missed. Then compare that list with the projects your change touched. In the hash details you diffed earlier, the entries that changed between runs will belong to a dependency's files rather than the project's own, which tells you which branch of the graph to follow. nx show project <name> confirms which named inputs the target uses, so you can check whether a ^ input is pulling those files in.

Implicit dependencies make the affected set larger. An entry in implicitDependencies creates a graph edge that no import statement backs, so the link between the two projects does not appear anywhere in the source code. Platform teams often add these for code generators, shared schemas, or deployment manifests and then lose track of them. Because each implicit edge carries ^ inputs to every project downstream of it, one implicit dependency on a frequently edited project can cause cache misses across a large part of the workspace. When a miss surprises you, check these edges in the graph view before you narrow any inputs.

How should you fix task inputs, and when should you avoid narrowing them?

Start in nx.json. Define a production named input that begins from default and subtracts what never reaches the build output: negation patterns for spec files, test configs, Markdown docs, and stories. Point build targets at production while test targets keep default, so editing a test re-runs tests without rebuilding dependents. Add {env: ...} or {runtime: ...} inputs only when the value actually changes output, such as a build-time API base URL. Each extra input fragments the cache. Write generated artifacts outside source roots so codegen output never feeds back into the hash of the project that produced it.

Approach Correctness Hit rate Maintenance cost
Broad project-root hashing High Low Low
Precise inputs High if verified High Moderate, needs review as tooling changes
Cache-busting workarounds Unpredictable Erratic High, hides the root cause

Do not exclude a file unless you know it does not affect output. A miss costs minutes. A false hit ships a stale build and reports no error.

Verify both directions after every change:

  1. Rerun with nothing changed. It should hit.
  2. Edit an excluded file. It should still hit.
  3. Edit a relevant source file. It should miss.

Illustrative estimate: assume 40 CI runs a day, with precise inputs avoiding 6 minutes of rebuilds per run. That saves about 4 hours of compute per day and shortens the wait on each PR. Re-measure hit rates after Nx upgrades, because hashing behavior can change between releases.

What are the alternatives to diffing hash details?

Diffing hash details is not the only way to respond to a cache miss. The other options are faster to try, but each one either leaves the cause unknown or costs more compute.

  • Bypass or clear the cache. --skip-nx-cache on a single run, or nx reset to clear the local cache and daemon state, will tell you whether a stale or corrupted cache entry is involved. Neither tells you which input changed, and using them routinely means every run pays the full execution cost.
  • Disable caching for the target. Setting "cache": false on a target is the right choice for tasks that are inherently nondeterministic or have side effects, such as deployments or tasks that call external services. For a build that should be cacheable, it hides the problem instead of fixing it.
  • Bisect the change. If a target started missing after some commit, you can check out commits between a known-good and a known-bad point and rerun the task until you find the commit that introduced the miss. This works without access to hash details, but it is slow in large workspaces and does not show which input inside that commit was responsible. It also cannot explain CI-versus-local differences, because both runs are on the same commit.
  • Inspect configuration only. Reading nx show project output and the project graph, without comparing two runs, can catch obvious mistakes such as artifacts under the project root or spec files in production inputs. It cannot detect environment-specific causes such as per-runner environment variables, runtime command output, or line-ending differences, because those only appear in the values recorded at hash time.
  • Broaden inputs and accept lower hit rates. For small workspaces or rarely run targets, the simplest fix may be to leave inputs broad and not spend time tuning them. This is a valid trade-off when the cost of a miss is low.

In practice these combine well with hash-detail diffing. Use a skip-cache run to confirm that replay is involved, use configuration inspection to understand the input definition, and use the component diff to find the specific value that changed.

How can this save engineering time?

The time savings come from two separate places: less compute spent repeating tasks, and less engineer time spent investigating misses.

Faster investigations. Without a component-level diff, debugging a miss usually means changing configuration, rerunning the pipeline, and checking whether the hit came back, one guess at a time. Each attempt costs a full CI cycle. A component diff reduces that to one comparison that points at a single input category, plus a check of the resolved configuration.

Illustrative estimate: assume an engineer spends 3 hours on a trial-and-error investigation versus 45 minutes with a component diff, and assume the team hits 4 unexplained misses a month. That comes to about 9 hours of engineer time saved per month. The numbers are assumed inputs for the calculation, not measurements. Substitute your own.

Fewer repeated runs. Once the root cause is fixed rather than worked around, tasks stop re-executing on every pipeline. The compute estimate in the previous section shows how quickly that adds up when many runs are affected. Developers also wait less for PR feedback, and they stop rerunning pipelines on the assumption that the cache is unreliable.

Fewer false hits. The verification steps above protect against the more expensive failure: a stale artifact that passes CI and ships. Any time saved by narrowing inputs is lost if you later have to trace a production issue back to a cached build that should have rebuilt. That is why each input change should go through the three-step verification.

Reusable process. The capture, normalize and diff script and the nx show project checks can be run by anyone on the team, so investigating cache behavior does not depend on the one person who knows the configuration history. Running the same checks after each Nx upgrade catches changes in plugin inference or hashing behavior before they show up as slower pipelines.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to nx cache miss debug, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.