actions/cache "Cache size of ... exceeds ... limit" in CI

actions/cache compresses the requested paths and refuses to upload when the archive is over the per-cache limit (10 GB on github.com). It logs the size and skips the save, so the next run is a cache miss.

What this error means

The post step warns "Cache size of ~X B (Y MB) is over the 10GB limit, not saving cache." The job succeeds but no cache is stored, so every run rebuilds from cold.

Cache Size: ~11264 MB (11811160064 B)
Warning: Cache size of ~11264 MB (11811160064 B) is over the 10GB limit, not saving cache.

Common causes

The cached path is too broad

Caching a whole build tree, a node_modules plus build output, or a Docker layer dir can balloon past 10 GB once compressed.

Stale or duplicated content accumulated in the path

Old toolchains, multiple platform binaries, or test artifacts living under the cached directory inflate the archive over time.

How to fix it

Cache only the dependency directory, not build output

1. Narrow path to just the package manager cache or store.
2. Exclude build output, logs, and test artifacts from the cached path.
3. Re-run and confirm the post step now reports a size under the limit and saves.

- uses: actions/cache@v4
  with:
    path: |
      ~/.cache/pip
      ~/.cargo/registry
    key: deps-${{ runner.os }}-${{ hashFiles('**/lockfile') }}

Prune the directory before the save

Run a cleanup step that removes stale or oversized content so the archive stays under 10 GB, or split into multiple smaller caches with distinct keys.

How to prevent it

• Cache dependency stores, not compiled output or artifacts.
• Keep an eye on total repo cache usage (10 GB per repo across all caches).
• Split very large caches into separate keyed caches by component.

Related guides