GitHub Actions Cache Miss From a "Cache Version" Mismatch

A cache with an identical key still misses because actions/cache also computes a hidden "version" from the path list, the compression method, and the runner OS. If any of those differ between save and restore, the entry does not match.

What this error means

Two runs use the exact same cache key but the restore misses, because something other than the key - the cached paths, the OS, or the archive tool - changed and altered the internal cache version.

# save job
path: node_modules
# restore job - same key, but different path list ⇒ different cache version ⇒ MISS
path: |
  node_modules
  ~/.npm

Common causes

Path list differs between save and restore

The cache version is derived partly from the set of paths. Adding, removing, or reordering paths between the save and restore changes the version, so the same key no longer matches.

Runner OS or compression tool changed

A different runner OS (or a change in the available tar/zstd) shifts the computed version, causing a miss even with a stable key.

How to fix it

Keep path and key identical across save/restore

Define the cache inputs once (or in a shared composite) so save and restore use the exact same paths and key.

# use identical path + key in both the saving and restoring jobs
- uses: actions/cache@v4
  with:
    path: node_modules
    key: deps-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

Account for OS in the key

1. Include runner.os in the key so caches are not shared across incompatible OSes by accident.
2. Do not change the path list between the save and restore of the same logical cache.
3. Centralize cache config so every consumer uses the same paths.

How to prevent it

• Use identical path lists for the save and restore of a cache.
• Include runner.os in the key to avoid cross-OS confusion.
• Share cache configuration so inputs stay consistent.

Related guides