GitHub Actions

Problem

A workflow's cache step reports a cache miss every run (or fails outright), so dependencies reinstall from scratch instead of restoring from cache.

Symptoms

• Cache not found for input keys
• Every run shows a cache miss regardless of whether dependencies actually changed
• actions/cache errors with a permissions or size-limit message

Root Cause

The cache key doesn't match between runs (often derived from something that changes every run, like a timestamp or full commit SHA instead of a lockfile hash), the cache was evicted (7 days unused, or the repo's 10GB total cache cap), or the workflow lacks permission to write to the cache (common on PRs from forks).

Solution

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

restore-keys: |
  npm-

Prevention

• Key caches off lockfile hashes, never off run-specific values
• Keep cache paths as narrow as possible — just the package manager's store, when supported
• Set up restore-keys fallbacks for graceful partial hits
• Periodically check total cache usage against the 10GB repo cap

References

• Caching dependencies