GitHub Actions "reserveCache failed: Cache size exceeds limit"

By Daniel Zoghalchali·Latchkey

Before uploading, the cache client reserves space. The reservation fails if the entry exceeds the per-cache size limit or the repository has hit its total cache quota (caches are evicted by least-recently-used).

What this error means

The cache save step warns that reserveCache failed with a size or quota message; the cache is not saved.

Failed to save: reserveCache failed: Cache size of ~12000 MB (12582912000 B) is over the 10GB limit, not saving cache.
Warning: Cache save failed.

Diagnose it: was the cache hit, and was it the right one?

Cache bugs split into three shapes and they need different fixes: the cache never saved, it saved but the key never matches on restore, or it restored a stale entry through a restore-keys prefix and is now poisoning the build. The step output tells you which one you have.

- uses: actions/cache@v4
  id: cache
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

- name: What happened
  run: |
    echo "exact hit: ${{ steps.cache.outputs.cache-hit }}"
    echo "key used:  ${{ steps.cache.outputs.cache-matched-key }}"

Common causes

Entry over the per-cache size limit

A single cache entry exceeds the 10 GB per-cache cap.

Repo cache quota exhausted

The repository total cache storage is full; old caches are evicted but a too-large new entry still fails.

How to fix it

Shrink what you cache

1. Cache only the package manager store, not entire build trees.
2. Exclude large generated artifacts from the cached path.
3. Split into multiple smaller caches if needed.

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-${{ hashFiles('**/requirements*.txt') }}

Cache limits that produce confusing failures

• Repository cache is capped at 10 GB. Past that, GitHub evicts least-recently-used entries, so a large cache can silently stop persisting.
• Caches are scoped by branch. A cache written on a feature branch is not visible to another feature branch, only to its base and its own descendants.
• An entry not read for 7 days is evicted, so a rarely-run workflow effectively never has a warm cache.
• Restoring a cache built for a different tool version is worse than a cold start, because you get a corrupted tree instead of a clean install. Always include the tool version in the key.

How to prevent it

• Keep cache entries well under the per-cache limit.
• Prune stale caches and avoid caching reproducible build output.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions