actions/cache restore-keys partial-hit confusion in CI

By Kaveh Alemi·Latchkey

When the exact key misses but a restore-keys prefix matches, actions/cache restores the closest older cache and logs "Cache restored from key: <prefix>...", but it sets cache-hit to false because the exact key was not found. Steps gated on cache-hit == true then behave as if nothing was restored.

What this error means

The log shows "Cache not found for input keys: <exact-key>" followed by "Cache restored from key: <prefix-key>", yet steps.cache.outputs.cache-hit is false, so a conditional install or save runs unexpectedly.

Cache not found for input keys: deps-Linux-abc123
Cache restored from key: deps-Linux-
Cache hit: false

Common causes

cache-hit is only true on an exact key match

A restore-keys prefix hit still restores files but reports cache-hit: false, by design, because the exact key did not match.

A conditional was gated on cache-hit, not on restoration

Steps using if: steps.cache.outputs.cache-hit != 'true' run even though an older cache was restored, sometimes redoing work.

How to fix it

Use cache-matched-key for partial-hit logic

The action exposes cache-matched-key, which is set on both exact and prefix hits. Branch on it when you only care that something restored.

- if: steps.cache.outputs.cache-matched-key == ''
  run: echo "true cold cache - install fully"

Understand the two outputs and gate correctly

1. Use cache-hit only to detect an exact-key hit.
2. Use cache-matched-key to detect any restore (exact or prefix).
3. Keep your save step unconditional so the new exact key is stored.

How to prevent it

• Distinguish cache-hit (exact) from cache-matched-key (any match).
• Do not skip a save just because a prefix restored an older cache.
• Document which output your conditionals depend on.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions