GitLab CI "Failed to extract cache" - Cache Not Restored

A job that should reuse a cache instead rebuilds from scratch. GitLab found no cache for the key, was told only to push it, or ran on a runner that cannot see the cache.

What this error means

Logs show "Checking cache for <key>... no cache" or "Failed to extract cache" instead of "Successfully extracted cache", and dependency steps reinstall everything every run.

gitlab-ci

Checking cache for node-default-protected...
WARNING: file does not exist
Failed to extract cache

Common causes

Cache key changes every run

A key built from a volatile value (commit SHA, timestamp) never matches a prior run, so every job is a miss.

Push-only policy or key/paths mismatch

A job set to policy: push writes but never restores, or producer and consumer jobs use different key/paths, so nothing lines up.

Runners do not share cache storage

Local runner caches are per-host. Across multiple runners without a distributed cache (S3/GCS), one runner cannot read another's cache.

How to fix it

Key the cache on the lockfile

.gitlab-ci.yml

cache:
  key:
    files:
      - package-lock.json
  paths:
    - node_modules/
  policy: pull-push

Share cache across runners

Configure a distributed cache (S3/GCS) in the runner config.toml.
Ensure producer and consumer jobs use identical key and paths.
Use pull-push on jobs that both read and update the cache.

How to prevent it

Key caches on lockfiles, never on SHAs or timestamps.
Use a distributed cache when more than one runner is involved.
Keep key/paths consistent between producer and consumer jobs.