GitLab CI cache not working: "Failed to extract cache" and fixes
Short answer
A GitLab CI cache is best effort: a job can always start without it. When the cache is never found, the usual reasons are a key that changes every pipeline, protected and unprotected branches getting separate caches (keys end in -protected or -non_protected), and jobs landing on runners that don't share a cache, which the log shows as "No URL provided". A cache isn't saved when the job fails, unless cache:when is always or on_failure, or when its paths are outside the project directory. Use artifacts, not cache, to pass build output between jobs. To start over, change cache:key or select Clear runner caches on the Pipelines page.
Every pipeline downloads the same dependencies again, or the log says “Failed to extract cache”. GitLab’s cache is an optimization, never a guarantee, but a cache that’s never found usually has a specific cause. Here are the causes in GitLab 19.5, and the fix for each.
Read the cache lines in the log
The runner logs the cache in two sections, Restoring cache before the script and Saving cache for successful job after it:
Restoring cache
Checking cache for deps-non_protected...
No URL provided, cache will not be downloaded from shared cache server. Instead a local version of cache will be extracted.
WARNING: Cache file does not exist
Failed to extract cache
...
Saving cache for successful job
Creating cache deps-non_protected...
.npm/: found 1203 matching artifact files and directories
No URL provided, cache will not be uploaded to shared cache server. Cache will be stored only locally.
Created cache
| Line | Means |
|---|---|
| Checking cache for … | The key the runner looks for, with GitLab’s protection suffix. |
| No URL provided, cache will not be downloaded from shared cache server | This runner has no shared cache: it only looks on its own machine. |
| WARNING: Cache file does not exist, then Failed to extract cache | Nothing is stored under that key yet. With an S3 or Google Cloud Storage cache, the first line reads WARNING: file does not exist. |
| Successfully extracted cache | It worked. |
| … due to policy | cache:policy skipped the step: a push job doesn’t download, and a pull job doesn’t upload. |
| no matching files, then WARNING: No files to cache. | A cache path matched nothing in the project directory, so nothing was saved, even though the next line says Created cache. The warning says “artifact”, but here it’s about the cache. |
Why the cache is never found
- The key changes every time. A key built from
$CI_PIPELINE_IDis new in every pipeline, and one from$CI_COMMIT_SHAin every commit. Use$CI_COMMIT_REF_SLUGfor a cache per branch, orkey: files:with your lock file, so the key only changes when dependencies do. - Protected and unprotected branches get separate caches. GitLab adds
-protectedor-non_protectedto every key. A pipeline gets the protected cache on a protected branch or tag, if the user who starts it can merge or create there, or when a Maintainer or Owner starts it. So with the same key, a Developer’s feature-branch pipeline doesn’t read the cachemainsaved, and a Developer and a Maintainer get different caches on one feature branch. - The jobs ran on different runners. A cache lives where the runner that made it keeps it: on its machine, unless the runner has a distributed cache such as S3. “No URL provided” means it hasn’t. Use one runner for the project, configure a shared cache in each runner’s
config.toml, or send the jobs to the same runner with tags. GitLab.com’s instance runners already share their cache. - Two jobs share a key but cache different paths. Each save replaces the other’s
cache.zip. Give each its own key.
If protected and unprotected branches should share, set unprotect: true on the cache, or clear Use separate caches for protected branches under Settings › CI/CD › General pipelines. Both let anyone who can push to an unprotected branch write the cache a protected branch reads, so GitLab advises it only where every Developer is highly trusted.
To fall back to another cache when the key isn’t found, list up to five fallback_keys, such as cache-$CI_DEFAULT_BRANCH. They get the same suffixes.
Why the cache isn’t saved
-
The job failed.
cache:whendefaults toon_success. Setwhen: alwaysto save the cache whatever happens, oron_failurefor failures only. -
The path is outside the project. Cache paths, like artifact paths, are relative to the project directory and can’t point outside it. Most tools cache in your home folder, so move their cache into the project:
default: cache: key: files: - package-lock.json paths: - .npm/ before_script: - npm ci --cache .npm --prefer-offlineFor pip, set
PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"; for Go modules,GOPATH: $CI_PROJECT_DIR/.go. -
The policy is
pull. A job withpolicy: pullonly downloads. Give one jobpull-push, the default, orpush, so something writes the cache. -
The job’s
cachereplaced the default. A job with its owncachedoesn’t merge withdefault: cache: it uses only its own.
A job can have at most four caches, and a key can’t contain / or consist only of dots.
Cache or artifacts
Use the cache for things you can download again, like packages, where a miss only costs time. Use artifacts for files a later job must have, like a build: GitLab stores artifacts and passes them on. The cache is restored before artifacts, so for a path in both, the artifact’s copy can overwrite the cached one. When artifacts go missing, see GitLab CI artifacts: no matching files and fixes.
Start with a fresh cache
- Change
cache:key. The next pipeline uses a new cache. - Clear runner caches. In Build › Pipelines, select Clear runner caches (Developer role). The next commit gets a new cache name; the old files stay on the runner until someone deletes them.
After clearing, the next pipeline fetches every dependency again, so pin dependency versions to get the same ones back.
On your phone
MergeBell shows a job’s log live, so you can watch the Restoring cache lines while a slow job runs, and cancel it or retry it on the free tier. Cache settings live in .gitlab-ci.yml and the runner’s configuration, and Clear runner caches needs GitLab in a browser. If a job stays pending, see GitLab job stuck in pending.
Frequently asked questions
What does "Failed to extract cache" mean in GitLab CI?
The runner couldn't restore a cache, so the job runs without one. Usually there's no cache under that key, and the line before says why: "Cache file does not exist", or with an S3 or Google Cloud Storage cache, "file does not exist". That's normal on the first run with a new key, after Clear runner caches, or on a runner that doesn't share its cache with the one that saved it. A download error or a broken archive ends the same way.
What does "No URL provided, cache will not be downloaded from shared cache server" mean?
The runner has no shared cache, such as S3 or Google Cloud Storage, configured, so it only looks on its own machine. If your jobs run on several runners, each one keeps its own cache. Use a single runner for the project, or configure a distributed cache in the runner's config.toml. GitLab.com's instance runners already share their cache.
Why doesn't my feature branch use the cache from main?
GitLab adds -protected or -non_protected to cache keys, so protected and unprotected branches don't share caches. A pipeline gets the protected cache on a protected branch or tag, if the user can merge or create it there, or when a Maintainer or Owner starts it. Set cache:unprotect: true on the cache, or clear Use separate caches for protected branches, if every Developer can be trusted with the protected cache.
Why is my GitLab CI cache not saved?
By default the cache is saved only when the job succeeds: set cache:when: always to save it after failures too, or on_failure for failures only. It's also skipped with cache:policy: pull, and paths outside the project directory, such as ~/.npm, can't be cached at all. Point the tool's cache into the project, for example with npm ci --cache .npm.
Should I use cache or artifacts in GitLab CI?
Use cache for dependencies you download, like npm or pip packages, where a miss only makes the job slower. Use artifacts for files a later job must have, like a build output: GitLab stores them and passes them to later jobs. The cache is restored before artifacts, so for a path in both, the artifact's copy can overwrite the cached one.
Sources
- GitLab docs — Caching in GitLab CI/CD
- GitLab docs — Cache key names (protected suffixes)
- GitLab docs — cache keyword
- GitLab docs — Caching examples
- GitLab Runner docs — Distributed runners caching
- GitLab Runner source — cache messages (shells/abstract.go)
- GitLab Runner source — cache download (cache_extractor.go)
Checked against these pages on 3 November 2026. GitLab changes quickly — if something here no longer matches, tell us and we will fix it.
Do this from your phone with MergeBell
Free for the whole review loop: the To-Do inbox, diffs and line comments, approve and merge, pipelines with retry, and push alerts for your To-Dos. Works with gitlab.com and self-managed GitLab 16.0+.
Get MergeBell for iPhoneGet MergeBell for Android
On the App Store for iOS 26 or later and on Google Play for Android 12 or later. An independent app, not affiliated with GitLab Inc.