GitHub Actions cache/restore fail-on-cache-miss Fails the Job

A restore-only cache step fails the job because fail-on-cache-miss: true treats a missing exact-key cache as an error. It is meant to enforce that a prior job populated the cache, but it surprises pipelines expecting a soft miss.

What this error means

An actions/cache/restore step errors with a cache-miss failure instead of continuing, even though a normal cache miss should be tolerated, because fail-on-cache-miss was enabled.

- uses: actions/cache/restore@v4
  with:
    path: dist
    key: build-${{ github.sha }}
    fail-on-cache-miss: true   # no exact-key hit -> job fails

Common causes

fail-on-cache-miss enabled with no exact hit

fail-on-cache-miss requires an exact key match. If the keyed cache was never saved (or the key changed), the step fails hard by design.

Expecting restore-keys to satisfy it

A restore-keys prefix hit is still a partial restore, not an exact-key hit. fail-on-cache-miss is about the exact key, so a prefix match does not prevent the failure.

How to fix it

Only enforce it when the cache must exist

Use fail-on-cache-miss only in a consumer job that requires an upstream job to have saved the exact key.

# producer job saved key build-<sha>; consumer requires it
- uses: actions/cache/restore@v4
  with:
    path: dist
    key: build-${{ github.sha }}
    fail-on-cache-miss: true

Otherwise allow a soft miss

1. Drop fail-on-cache-miss (default false) when a miss should just rebuild.
2. Ensure the producing job actually saved the exact key you require.
3. Remember restore-keys give a partial hit but do not satisfy fail-on-cache-miss.

How to prevent it

• Use fail-on-cache-miss only to assert an upstream save happened.
• Match the exact key between the producer and consumer jobs.
• Leave it off for caches where a miss should soft-fall-back to a rebuild.

Related guides