Skip to content

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

  1. Pin actions/cache@v4 or newer, and update with Dependabot.
  2. Save from one job, restore everywhere.
  3. Limit matrix parallelism for large fan-outs.
  4. 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.