GitHub Actions cache hit but restore left files missing

actions/cache reported a key match, but the restored archive did not contain every path the build needs. The cache was saved with a narrower path set than the restore expects, so dependent steps still rebuild or fail.

What this error means

cache-hit is true, yet a build step behaves as if the dependency directory is empty or stale.

github-actions

Cache restored successfully
Cache restored from key: deps-${{ hashFiles('package-lock.json') }}
Error: Cannot find module 'esbuild' (native binary missing from restored cache)

Common causes

Save and restore path lists differ

The cache was saved with one set of paths but a later restore (or a different job) expects more, so some directories are absent.

Platform-specific files cached cross-OS

Native binaries restored on a different OS or arch than they were built on are incompatible even though the key matched.

How to fix it

Align paths and include the OS in the key

List every directory the build needs under the cache path, identically on save and restore.
Add runner.os (and arch when relevant) to the key so native artifacts are not shared across platforms.
Re-run.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: |
      node_modules
      ~/.cache/ms-playwright
    key: deps-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

How to prevent it

Keep save and restore path lists identical and complete.
Scope keys by OS and architecture when caching native binaries.