How does Nx compute a task hash?
Nx caches task results so that work it has already done doesn't run again. Before a target such as build or test runs, Nx computes a hash for that task and looks it up in the local cache and, if one is configured, the remote cache. A hit replays the stored terminal output and restores the output files. A miss means no stored entry matches the hash, so the task runs in full. To debug a miss, you need to know what went into the hash.
What goes into the hash
- Resolved input files. Nx expands the target's input globs against the project's files and hashes the contents of every match. The hash covers the full set of matched files, so adding or removing a file also changes it.
- Dependency hashes via
^inputs. An input prefixed with^pulls in the matching inputs from the projects this one depends on. A change in a library therefore changes the hash of every dependent task that declares a^input. - External dependency versions. Nx reads installed package versions from the lockfile. How precisely it maps a lockfile change to the individual projects that use a package varies between Nx versions. Check how your version behaves instead of assuming per-package precision.
- Target options and arguments. Configured options and command-line flags are part of the hash, so
--configuration=productionand the default configuration produce different hashes. - Declared env and runtime inputs. Environment variables and runtime command outputs are included only if you declare them.
A change in any one of these components produces a different hash, and that alone is enough to cause a miss.
+--------------------------------+
| Resolved input files |---+
| (globs -> matched file content)| |
+--------------------------------+ |
| ^ inputs: dependency project |---+
| hashes | |
+--------------------------------+ | +-------------+
| External dep versions |---+---->| Task hash |
| (from lockfile) | | +------+------+
+--------------------------------+ | |
| Target options and CLI args |---+ v
| (e.g. --configuration=...) | | +-------------+
+--------------------------------+ | | Cache lookup|
| Declared env / runtime inputs |---+ | local/remote|
| (only if declared) | +--+-------+--+
+--------------------------------+ | |
hit v v miss
+------------+ +-----------------------+
| Hit: replay| | Miss: no stored entry |
| output and | | matches the hash, so |
| restore | | the task runs in full |
| files | | |
+------------+ +-----------------------+
Any one input that changes -> different task hash -> cache miss
Nx combines five input components into a single task hash and looks it up in the local and remote cache, so a change in any one component produces a different hash and a cache miss.
Who should use this debugging approach?
This approach is for anyone working in an Nx workspace with caching enabled who sees tasks rerun when they expected a hit, or replay when they expected a rerun:
- Platform and build engineers who own
nx.json,targetDefaults, and the CI pipeline. They decide which inputs every project hashes, so a mistake in their configuration affects the whole repository. - Teams sharing a remote cache between developer machines and CI. A shared cache only pays off when hashes match across machines, and local-versus-CI mismatches are among the hardest misses to diagnose by guessing.
- Developers on large dependency graphs, where one unexpected miss in a widely used library cascades into rebuilds of every dependent project.
- Anyone upgrading Nx or its plugins, because inferred inputs can change without any edit to the repository.
It matters less in small workspaces where every task finishes in seconds, or where caching is turned off. In those cases a miss costs little and tuning inputs is rarely worth the effort.
How does cache miss debugging work?
The method rests on one property: the task hash is a deterministic function of its inputs. The same inputs always produce the same hash. So when two runs that should match produce different hashes, at least one input differs between them, and your job is to find which one.
In practice that takes three things:
- The resolved configuration.
nx show project <name>shows the inputs Nx actually uses after merging plugins,targetDefaults, and project files. This tells you what can feed the hash. - The per-input hash details from two runs, one that hit and one that missed, or one local run and one CI run of the same commit. These tell you what did feed the hash in each run.
- A diff of the two. The entry that differs points to a specific file, environment variable, runtime value, external dependency, or upstream project hash. You trace that entry back to the
inputsornamedInputsdefinition that included it, then fix the definition.
The rest of this article covers each piece: reading resolved inputs, how named inputs shape the file set, a step-by-step workflow, common causes and fixes, and local-versus-CI differences.
How do you see which inputs a task actually resolves to?
Nx never hashes the inputs array you wrote. It hashes the configuration that results after merging plugins, targetDefaults, and project files. To see that resolved configuration, run nx show project <name>. Add --json to get output you can search with jq, or --web to open the project details view. Find the target, such as build or test, and read its inputs entry. The task is hashed against that list.
Compare the resolved list with the configuration you expected to apply. Configuration is applied in layers:
namedInputsinnx.jsondefines reusable sets such asdefaultandproduction. A project can redefine a named input in its ownproject.json, and the project's definition wins for that project.targetDefaultsinnx.jsonsets inputs for every target with a matching name or executor.inputson the target inproject.jsonreplaces the default array. The two arrays are not concatenated. If you add a single file pattern at the project level and forget to listproductionand^productionagain, the target silently stops depending on everything those named inputs covered.
Inferred targets from plugins
Plugins that infer targets from tool config files also generate those targets' inputs. These usually include the tool's config file and sometimes the tool's own dependency. The inputs come from the plugin's code, not from your repository. That means a plugin upgrade can add, remove, or rename inputs even when you haven't edited any configuration. Your targetDefaults and project-level settings are still layered on top of the inferred values.
As a result, a cache miss right after a dependency bump is often a configuration change, not a bug. After every plugin upgrade, run nx show project again and diff the resolved inputs against the output from before the upgrade.
#!/usr/bin/env bash
set -euo pipefail
PROJECT="my-app" # placeholder project name
TARGET="build" # target whose cache keeps missing
show_inputs() {
npx nx show project "$PROJECT" --json | jq --arg t "$TARGET" '.targets[$t].inputs'
}
show_inputs > inputs-before.json
read -r -p "Upgrade plugins now, then press Enter to continue... "
show_inputs > inputs-after.json
diff -u inputs-before.json inputs-after.json && echo "No change in resolved inputs for $PROJECT:$TARGET"
Captures a target's effective inputs from nx show project --json before and after a plugin upgrade and diffs them to reveal inputs the plugin added, removed, or renamed.
How do namedInputs like 'default' and 'production' work?
A named input is a reusable, labelled list of file globs and other input definitions, declared under namedInputs in nx.json and referenced by name from a target's inputs array. Instead of repeating the same glob list in every project, you define it once and every target that names it hashes the same file set.
Two names follow a common convention. default usually resolves to everything under {projectRoot}, often combined with a workspace-wide set such as sharedGlobals. production usually starts from default and then excludes files that cannot affect shipped output: spec and test files, test-only tsconfig files, test runner config, and lint config. Exclusions use a ! prefix on the glob.
The example below sets build to use production and ^production in targetDefaults, while test uses default and ^production. The ^ prefix means "this named input, resolved in each project this one depends on." A build therefore hashes its own production files plus its dependencies' production files.
If you use default everywhere, every file in the project feeds the build hash. Editing user.service.spec.ts changes the hash, so build reruns even though the compiled output is identical. Because the build's hash also feeds downstream projects through ^ inputs, a single test edit can invalidate builds across the dependency graph.
| Target type | Recommended inputs | Why |
|---|---|---|
build |
production, ^production |
Only shipped source and dependency source affect output |
test |
default, ^production |
Needs its own specs, but only dependencies' source |
lint |
default, plus the root lint config |
Lints all files, and rule changes must invalidate it |
e2e |
default, ^production |
Exercises built dependencies, not their tests |
{
"namedInputs": {
"sharedGlobals": ["{workspaceRoot}/tsconfig.base.json"],
"default": ["{projectRoot}/**/*", "sharedGlobals"],
"production": [
"default",
"!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)",
"!{projectRoot}/tsconfig.spec.json",
"!{projectRoot}/jest.config.[jt]s",
"!{projectRoot}/.eslintrc.json",
"!{projectRoot}/eslint.config.mjs"
]
},
"targetDefaults": {
"build": {
"dependsOn": ["^build"],
"inputs": ["production", "^production"],
"cache": true
},
"test": {
"inputs": ["default", "^production"],
"cache": true
},
"lint": {
"inputs": ["default", "{workspaceRoot}/eslint.config.mjs"],
"cache": true
}
}
}
An nx.json where build hashes only production files from the project and its dependencies, while test and lint hash all project files, so editing a spec file leaves the build cache intact.
A repeatable workflow for nx cache miss debugging
With the inputs mapped, debug misses in a fixed order. Each step rules out a class of causes before you start editing configuration.
-
Run the same task twice in a row, unchanged. If the second run misses, the hash is unstable. Something in the inputs changes between runs without any edit from you. Typical sources are a generated file written inside the project, a timestamp, or an environment variable that varies per shell. Fix this first, because no inputs tuning helps while the hash drifts.
-
Capture hash details for a hit and a miss. Record the hash details from a run that hit the cache. Then make the change that unexpectedly caused a miss and record them again. You are comparing the list of hashed inputs, which covers files, runtime values, environment variables and dependency hashes, not just the final hash string.
-
Diff the two and isolate the input that differs. Usually only one entry changes, such as a file you didn't expect to be included or a dependency's hash. Trace that entry back to the
inputsornamedInputsdefinition that pulled it in. -
Fix the configuration, then repeat step 1. Exclude the file, move it out of the project, or narrow the named input. Then confirm the hash is stable again.
Use --skip-nx-cache only to confirm that a problem is cache-related. If a broken build still fails with caching bypassed, the cache is not the cause.
Where Nx stores or prints hash details differs between versions. Check the docs for your installed version rather than relying on a fixed path or output format.
#!/usr/bin/env bash
set -euo pipefail
TARGET="myapp:build"
npx nx run "$TARGET"
npx nx run "$TARGET"
diff <(jq -S . hash-hit.json) <(jq -S . hash-miss.json) || true
npx nx run "$TARGET" --skip-nx-cache
A shell outline of the workflow: check that the hash is stable, diff saved hash details from a hit and a miss, fix the inputs, and use --skip-nx-cache only to confirm a problem is cache-related.
What causes nx cache invalidation, and how do you fix each cause?
Each cause below shows up as a specific file or value in the hash details that differs between two runs. Match what you see to a row, then apply the fix.
| Cause | Why the hash changes | Fix |
|---|---|---|
Codegen output, local .env files, or coverage reports inside {projectRoot} |
Any file Nx can see under the project root is matched by default |
Add them to .gitignore or .nxignore, or exclude them with a !{projectRoot}/... pattern |
| Files rewritten on every run, such as build info or embedded timestamps | The content differs even when the source is unchanged | Write these files outside the project root, or exclude them from inputs |
Shared root files, such as a base tsconfig or the lockfile |
Every project that lists them is invalidated by any edit | Keep sharedGlobals short, and depend on external packages instead of whole files |
| Tool config that no input declares | Edits do not change the hash, so stale results are replayed | Add the config file to the target's inputs |
The last row is the opposite of a miss: it is a wrong hit. Env and runtime values cause the same problem when you leave them out.
If a build reads DEPLOY_TARGET, declare {"env": "DEPLOY_TARGET"}. If you omit it, a staging artifact can be restored for a production build. For a Node version, use {"runtime": "node --version"}.
Do not hash a commit SHA or any other value that changes on every run. It guarantees a miss every time, which makes caching pointless.
A runtime command should print only the value that matters. If its output includes paths, hostnames, or full version banners, each machine produces a different hash, and the cache splits into separate entries per machine.
Why does a task hit the cache locally but miss in CI?
That same per-machine split explains most cases where a task hits the cache on a laptop but misses in CI. Don't guess at the cause. Capture the per-input hash breakdown from one local run and one CI run of the same commit, then diff them. Nx hashes each input separately, so the entry whose hash differs tells you which category below applies.
| Difference | Why it changes the hash | What the diff shows |
|---|---|---|
| Environment variables | An env input reads the variable directly. CI often sets values you never define locally, or sets different ones. |
One env: entry has a different hash. |
| Runtime command output | The command runs on each machine, and its output includes something machine-specific such as a tool version or a path. | A runtime: entry differs. Run that command by hand in both places and compare the text. |
| Lockfile after install | A non-frozen install in CI can rewrite the lockfile. A local lockfile with uncommitted edits has the same effect. | The lockfile entry or external dependency hashes differ. |
| CI-only generated files | Codegen, env files, or build stamps created by an earlier CI step fall inside a file glob. | A file appears in the CI list but not the local one, or the reverse. |
| Checkout depth | A shallow clone changes the output of git commands that depend on history, such as tag lookups or commit counts. |
A runtime: entry that calls git differs, even though the file hashes match. |
If every input hash matches but the overall task hash still differs, compare the dependency task hashes. The real difference is usually upstream, in a project the task depends on.
How can it save engineering time?
Debugging misses systematically saves time in four places:
- Fewer reruns of unchanged work. Every unexpected miss reruns a task whose output would have been identical. Once inputs exclude files that cannot affect output, such as specs in a build, routine edits stop triggering rebuilds locally and in CI. On a deep dependency graph this compounds, because a miss in a shared library also forces misses in every dependent task that declares a
^input. - Shorter CI runs and a useful remote cache. When local and CI hashes match, CI can restore results that developers or earlier pipeline runs already produced. When they don't match, the remote cache stores entries that are never hit again, and every pipeline pays for full runs.
- Less time spent guessing. Diffing per-input hash details points to the exact file, variable, or upstream project that changed. That replaces trial-and-error edits to
nx.json, and it replaces habits like runningnx resetor adding--skip-nx-cacheto scripts, both of which throw away cached work. - Fewer stale-hit incidents. The same workflow catches undeclared inputs, such as an env variable or a tool config file, that let Nx replay the wrong artifact. Finding those before they ship avoids debugging a production problem that the build logs give no sign of.
The illustrative estimate at the end of this article shows the arithmetic for one of these cases, excluding spec files from a build's inputs, under explicitly assumed inputs.
When should you avoid narrowing inputs, and what are the alternatives?
Narrowing inputs trades cache misses for a worse failure: the stale hit. Suppose production excludes a file the build actually reads, such as a JSON config loaded at compile time. Nx then replays an old artifact and reports success. A miss costs minutes. A stale hit ships the wrong output, and the logs give no sign of it. Only exclude a file when you can show it has no effect on the task's output.
Broad inputs, such as workspace-root files listed in sharedGlobals, are safe. The cost is that editing any one of them invalidates every project that depends on it.
| Option | Risk | Cost |
|---|---|---|
Narrow production inputs |
Stale hits if an exclusion is wrong | Low rerun rate |
Broad default or root inputs |
None for correctness | Frequent repo-wide invalidation |
--skip-nx-cache |
None | Full rerun for that invocation |
nx reset |
None | Clears the local cache and daemon state, so every task rebuilds afterward |
The last two help you confirm a suspicion. If people reach for them routinely, the inputs are probably misconfigured. Adding them to CI scripts discards caching on every run.
Illustrative estimate
Assume a backend service with a 4-minute build. A developer makes 20 edits a day, and 12 of them touch only *.spec.ts files. production is configured to exclude those files.
- With
default: all 20 edits trigger a rebuild, for 80 minutes of build time. - With
production: only the 8 source edits trigger a rebuild, for 32 minutes.
Test targets still rerun on spec edits in both cases. These figures are arithmetic on assumed inputs, not measured speedups.
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 debugging, 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
.envby 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.