actions/cache cache-hit output ignored, rebuilding every run in CI

By Kaveh Alemi·Latchkey

A cache can restore correctly yet save no time if the expensive step runs every run regardless. The cache-hit (and cache-matched-key) outputs exist so you can skip the rebuild on a hit; ignoring them means you pay the full cost even when the cache was restored.

What this error means

Logs show "Cache restored from key: ..." but the install or build step still takes full time on every run, because no if: condition gates it on the cache outputs.

Cache restored from key: build-Linux-abc123
# ...then the build step runs in full anyway, ignoring the restored cache

Common causes

No conditional gates the expensive step

The build or generate step has no if: referencing the cache output, so it executes whether or not the cache was restored.

The cache only stores inputs, not the built output

Caching just the dependency store still requires a build; to skip work you must cache the output and gate the build on a hit.

How to fix it

Gate the rebuild on the cache output

1. Give the cache step an id.
2. Add if: steps.<id>.outputs.cache-hit != 'true' to the expensive step.
3. Re-run; on a hit the build step is skipped and the cached output is used.

- id: build-cache
  uses: actions/cache@v4
  with:
    path: dist
    key: build-${{ hashFiles('src/**') }}
- if: steps.build-cache.outputs.cache-hit != 'true'
  run: npm run build

Cache the output, not only dependencies

To actually skip a build, cache the generated dist/target directory keyed by source hash, and restore it instead of rebuilding when the key hits.

How to prevent it

• Always branch the expensive step on cache-hit.
• Cache build output (keyed by source) when you want to skip builds.
• Verify wall-clock time actually drops on a cache hit.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions