GitLab CI "cache:fallback_keys" Errors - Fallback Cache Not Used

cache:fallback_keys lets a job restore an older cache when the exact key misses - useful on new branches. It fails to help when the fallback keys are wrong, ordered badly, or no prior cache exists for any of them.

What this error means

A job on a new branch still installs everything from scratch despite fallback_keys, or validation rejects the cache block. The fallbacks either do not match any stored cache or are configured incorrectly.

Job log

Checking cache for branch-feature-x...
No URL provided, cache will not be downloaded from shared cache server.
WARNING: file does not exist
# fallback_keys listed do not match any previously stored cache key

Common causes

Fallback keys never matched a stored cache

If no prior job ever wrote a cache under any of the fallback_keys, there is nothing to fall back to, so a fresh branch still starts cold.

Fallback keys not tied to a shared baseline

Fallbacks help only when they reference a broadly-written key (e.g. the default branch’s cache). Per-branch fallbacks that no one else writes never hit.

Distributed cache not configured

Across multiple runners, fallback restore needs a shared/distributed cache. Without it, a runner cannot see a cache another runner wrote.

How to fix it

Fall back to a baseline key

Write a branch-specific key but fall back to a stable default-branch cache so new branches warm-start.

.gitlab-ci.yml

cache:
  key: "deps-$CI_COMMIT_REF_SLUG"
  fallback_keys:
    - "deps-main"          # default branch's cache, written regularly
  paths:
    - node_modules/

Ensure a shared cache and a writer

Configure a distributed cache (S3/GCS) in the runner config.toml for multi-runner setups.
Make sure a regularly-run job writes the fallback key (usually on the default branch).
Order fallback_keys from most to least specific.

How to prevent it

Fall back to a default-branch cache that is written on every merge.
Use a distributed cache when more than one runner is involved.
Order fallback_keys from most specific to most general.