# Cache Key vs Restore Key: How CI Cache Lookups Work

> A cache key is the exact entry to save and look up; restore keys are prefix fallbacks for a near-miss. Learn how the two balance freshness and hits.

Source: https://latchkey.dev/learn/ci-cd-concepts/cache-key-vs-restore-key  
Updated: 2026-06-25

The cache key is the exact name you save under and look for first. Restore keys are prefixes that catch a near-miss, so a small change restores a useful older cache instead of nothing.

CI caching has two knobs that people conflate: the precise key and the fallback restore keys. Understanding how a lookup walks from one to the other is the key to both high hit rates and fresh data.

## The exact key

On save, the cache is stored under the key. On restore, the runner first looks for an exact match. A perfect match is the ideal: it restores precisely the cache for this dependency set. The key usually embeds a lockfile hash so it changes only when it should.

## Restore keys (prefix fallback)

If there is no exact match, the runner tries each restore key as a *prefix*, taking the most recent cache whose key starts with that prefix. This means a changed lockfile (new exact key, no exact hit) can still restore the previous run’s store and let the installer update just the delta.

```Exact key + prefix fallback
key: deps-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
  deps-
```

## Save vs restore semantics

- Save: writes under the exact key (no-op if that key already exists).
- Restore: exact key first, then restore-keys as prefixes, newest wins.
- A restore-key hit is partial - the installer reconciles the difference.

## Tuning the trade-off

Too specific a key with no restore keys → frequent total misses and cold installs. Too loose a prefix → you may restore a stale, bloated cache. A tight exact key plus a sensible prefix fallback gives you freshness on a match and a warm start on a miss.

## FAQ

### What is Cache key vs restore Key: how CI cache lookups work?

CI caching has two knobs that people conflate: the precise key and the fallback restore keys. Understanding how a lookup walks from one to the other is the key to both high hit rates and fresh data.

### The exact key?

On save, the cache is stored under the key. On restore, the runner first looks for an exact match. A perfect match is the ideal: it restores precisely the cache for this dependency set. The key usually embeds a lockfile hash so it changes only when it should.

### Restore keys (prefix fallback)?

If there is no exact match, the runner tries each restore key as a *prefix*, taking the most recent cache whose key starts with that prefix. This means a changed lockfile (new exact key, no exact hit) can still restore the previous run’s store and let the installer update just the delta.

### Tuning the trade-off?

Too specific a key with no restore keys → frequent total misses and cold installs. Too loose a prefix → you may restore a stale, bloated cache. A tight exact key plus a sensible prefix fallback gives you freshness on a match and a warm start on a miss.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt