Cache Service Responded With 429: Fix
Last updated
Failed to restore: Cache service responded with 429 means the GitHub Actions cache service refused your request because it was rate limited: HTTP 429 is "too many requests". It usually shows up when many jobs restore or save caches at the same moment, for example a large matrix starting together. By itself it is a warning: the cache step reports failure to restore or save, and the job carries on, just slower.
The exact message
Warning: Failed to restore: Cache service responded with 429
Warning: Failed to save: Cache service responded with 429
GitHub does not publish a fixed request rate for the cache service in its usage limits page, so there is no number to stay under. The practical approach is to make fewer requests, and make them less bunched together.
Fix 1: use a current version of actions/cache
Old versions of the cache action talk to a legacy service that GitHub has retired, and they fail in different ways. Use the current major version:
- uses: actions/cache@v4
with:
path: ~/.npm
key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
restore-keys: npm-${{ runner.os }}-
The same applies to the caches built into actions/setup-node, setup-python and setup-java: use their current versions.
Fix 2: one job saves, the others only restore
If 30 matrix jobs each save the same cache, you send 30 save requests for one cache entry, and 29 of them are wasted. Restore everywhere, save in one job:
- uses: actions/cache/restore@v4
id: cache
with:
path: ~/.npm
key: npm-${{ hashFiles('**/package-lock.json') }}
# ... install and test ...
- uses: actions/cache/save@v4
if: matrix.shard == 1 && steps.cache.outputs.cache-hit != 'true'
with:
path: ~/.npm
key: npm-${{ hashFiles('**/package-lock.json') }}
The id: cache on the restore step lets the save condition read its cache-hit output.
Fix 3: slow the start of a big matrix
strategy.max-parallel limits how many matrix jobs run at once, which also spreads out the cache requests.
strategy:
max-parallel: 10
matrix:
shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]
Fix 4: fewer, larger cache entries
Several small caches in one job means several requests. Combine cache paths that share a key, and avoid caching things that are quick to download. See GitHub Actions caching and cache limits.
Fix 5: re-run
Rate limits clear. If it was one bad moment, re-run the failed jobs. If it happens every run, apply the fixes above.
If the job fails because of the missing cache
A 429 on restore leaves you with a cache miss. If a later step depends on the cache and fails, see Cache not found for input keys. Do not set fail-on-cache-miss: true unless you want a miss to fail the build.
How to prevent it
- Pin
actions/cache@v4or newer, and update with Dependabot. - Save from one job, restore everywhere.
- Limit matrix parallelism for large fan-outs.
- Prefer a few well-chosen caches over many tiny ones.
FAQ
Does a 429 fail my workflow?
Not by default. The cache step logs a warning and the job continues, but without the cache it can take much longer.
Is this the same as the GitHub API rate limit?
No. This is the cache service. For the REST API limit see API rate limit exceeded.
Will a self-hosted runner avoid it?
Not by itself, because self-hosted runners use the same GitHub cache service. A local cache on the runner's disk avoids the service, at the cost of managing it.
Why did it start after nothing changed?
Rate limiting depends on load. A bigger matrix, more concurrent runs, or a busy period on GitHub's side can all trigger it.
Related
- Cache Cargo and Rust Builds in GitHub ActionsCache the Cargo registry, git dependencies and target directory in GitHub Actions with Swatinem/rust-cache or actions/cache, and avoid bloated caches.
- Cache Go Modules and Build Cache in GitHub ActionsCache Go modules (GOMODCACHE) and the build cache (GOCACHE) in GitHub Actions with setup-go or actions/cache. Keys, go.sum, and verifying hits.
- Cache Gradle Builds in GitHub ActionsCache Gradle dependencies and build cache in GitHub Actions with gradle/actions/setup-gradle or actions/cache. Keys, read-only PRs, cleanup and checks.
- Cache npm Dependencies in GitHub ActionsCache npm dependencies in GitHub Actions with setup-node or actions/cache. Working YAML, the right key, why not node_modules, and how to confirm a hit.