Nx "Cannot read cache" / cache miss in CI

Nx caches task outputs by a computed hash. If the cache directory is missing, unreadable, or never restored between CI jobs, every task is a cache miss and reruns from scratch, so the build is slow and the cache never helps.

What this error means

Nx cannot read the cache directory, or every task shows as executed rather than "read from cache", even when nothing changed between runs.

NX   Cannot read the cache directory: .nx/cache
Every task will run without caching.

Common causes

The cache directory is not persisted across jobs

Each CI job starts clean. Without restoring .nx/cache (or using Nx Cloud), the local cache is always empty and every task reruns.

Task outputs are not declared

If a target does not declare its outputs, Nx cannot cache them, so hits never happen even with a warm cache.

How to fix it

Restore the Nx cache between jobs

Cache .nx/cache keyed on your lockfile and source, or use Nx Cloud for a shared remote cache.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: .nx/cache
    key: nx-${{ hashFiles('**/package-lock.json') }}-${{ github.sha }}
    restore-keys: nx-${{ hashFiles('**/package-lock.json') }}-

Declare outputs so tasks are cacheable

Tell Nx where each target writes so it can capture and replay the outputs.

project.json

"build": {
  "outputs": ["{workspaceRoot}/dist/{projectRoot}"]
}

How to prevent it

Restore .nx/cache or use Nx Cloud so the cache survives between jobs.
Declare outputs on every cacheable target.
Key the cache on the lockfile so it invalidates on dependency changes.