GitHub Actions Cache Evicted - 10 GB Repo Cache Limit Exceeded

A cache you expected to be there is gone because GitHub enforces a 10 GB total cache limit per repository and evicts the least-recently-used entries once you exceed it.

What this error means

Caches restore inconsistently: a key that hit yesterday misses today. Large caches or many per-branch caches push the repo past 10 GB and older entries get evicted.

Actions log

Cache not found for input keys: build-${{ hashFiles(...) }}
# the entry existed earlier but was evicted under the 10 GB repo limit

Common causes

Total cache exceeds the 10 GB repo limit

GitHub caps total cache storage at 10 GB per repository and evicts least-recently-used entries beyond that. Large caches consume the budget fast.

Too many per-branch caches

Each branch can create its own caches. Many active branches with sizeable caches collectively blow past the limit.

How to fix it

Cache less and cache smaller

Cache the package manager download cache (for example ~/.npm) rather than the full installed tree where possible.
Narrow cached paths to what genuinely speeds up the build.
Prune stale caches via the cache management API or UI.

Scope keys to reduce duplication

Use shared restore-keys so branches reuse a common base cache instead of each storing a full copy.

.github/workflows/ci.yml

key: deps-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
restore-keys: |
  deps-${{ runner.os }}-

How to prevent it

Keep individual caches small and scoped to high-value paths.
Use restore-keys so branches share a base cache rather than duplicating it.
Periodically clear stale caches to stay under 10 GB.