← All posts
10 min readThe Cachely team

Fixing GitHub Actions cache errors: permission denied, cache not found, and failed saves

actions/cache failures cluster into a handful of shapes: a restore that dies with Permission denied, a cache that is mysteriously "not found" on one branch but exists on another, a save with no matching paths or a key conflict, and workflows on old versions that stopped working entirely. Each one has a specific cause and a specific fix - none of them is "retry the job". Here is the field guide.

Path Validation Error when saving the cache

Path Validation Error: Path(s) specified in the action for caching do(es) not exist, hence no cache is being saved.

This message means the save operation resolved the configured paths to no matches. The cache toolkit checks this before creating or uploading an archive. It does not establish a cache-service outage or an expired token. A restore miss earlier in the job is normal on a cold run; this warning says that the later save had nothing matching its paths. The cache action logs save errors as warnings, so a green job alone does not prove that a new cache was saved.

Check the path at save time, then change the part of the workflow that explains the mismatch:

  • Wrong location or pattern. Compare actions/cache's path with the directory the tool actually writes. A shell step running in apps/web can create apps/web/.cache, while a cache action resolving .cache from the workspace root looks elsewhere. Use the workspace-relative location or an explicit absolute path. The glob documentation defines relative paths against the current working directory; a shell step's working-directory does not configure a separate action's inputs.
  • The producer never populated the path, or cleanup removed it. Check whether the install or build step ran, where it wrote, and whether later cleanup deleted the directory before the post-job save. Keep restore before the work, and retain the generated cache until save completes. For an explicit actions/cache/save step, place it after the producer. If a job intentionally never creates that cache, condition its caching steps accordingly. Creating an empty directory can hide the warning without saving useful work.
  • Confusing a lockfile with a cache directory. With setup-node, cache-dependency-path selects the lockfiles used to generate the key. The action caches package-manager data rather than node_modules; see its caching documentation. Check the actual location with npm config get cache or pnpm store path, using the same tool version and configuration as the install. Changing the lockfile path alone does not create a missing cache directory.

For a literal directory, add this read-only Bash check after the producing step and before cleanup. Replace the example location with the directory your tool should create. This checks existence, not whether a wildcard matches or whether the contents are useful:

- name: Check the configured cache directory
  shell: bash
  env:
    CACHE_DIR: ${{ github.workspace }}/apps/web/.cache
  run: |
    if [ -d "$CACHE_DIR" ]; then
      echo "Configured cache directory exists"
    else
      echo "::warning::Configured cache directory is missing"
    fi

If the directory exists but the action still finds no matches, investigate the exact pattern, platform, and action version. An upstream report describes Windows matching failures with @actions/glob 0.6.1 bundled as ESM with Rollup in custom JavaScript actions. That report is a specific possible cause, not evidence that ordinary missing-path warnings share the same bug.

To verify recovery, use a run eligible to save a new key and confirm the save log reports success. An exact primary-key hit skips saving, so it cannot test this fix. A later run with the same key and accessible cache scope should restore the entry. These explanations were checked against upstream source and documentation on November 12, 2026; the diagnostic was checked locally with synthetic directories, not reproduced as a hosted GitHub Actions failure.

Permission denied during restore

A cache restore is a tar extraction into your paths. It fails with EACCES or Permission denied when the runner user cannot write over what is already there - and on a hosted runner that almost always means files owned by root. The usual culprits:

  • A container step wrote into the workspace. Steps running in Docker containers execute as the container's user - often root - so files they create (a node_modules, a build output) are root-owned on the host. A later restore into the same path cannot overwrite them.
  • A sudo install step created the cached directory. Caching a path like /usr/local/lib/something that was populated with sudo fails the same way in reverse: the extraction runs unprivileged and cannot write there.

Three fixes, in order of preference:

# 1) keep cached paths inside user-writable locations
path: ~/.npm            # package-manager caches, not system dirs

# 2) fix ownership after any root-writing step
- run: sudo chown -R "$(id -u):$(id -g)" node_modules dist

# 3) run the container step as the runner's uid
container:
  image: my-image
  options: --user 1001

The first is the durable one: cache package-manager cache directories (~/.npm, ~/.gradle/caches, ~/.cargo) rather than installed system paths or project directories a container may have touched.

"Cache not found" on a branch where you swear it exists

Cache entries are branch-scoped. A job can restore caches created on its own branch, the base branch of its pull request, or the repository's default branch - and nothing else. Two sibling feature branches never share entries, and a cache saved in a pull-request run is not visible to main. The pattern that follows from the rules: let the default branch populate shared caches (dependency caches especially), so every new branch starts warm from main's entries. If your misses spike on new branches, check whether anything on the default branch is actually saving with the same key prefix, and keep restore-keys as orderly fallbacks:

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

Also remember the eviction rules when a cache vanishes overnight: entries untouched for 7 days are removed, and once a repository exceeds its total cache quota (10 GB by default) the oldest entries are evicted until it fits. A busy monorepo with fat per-branch entries can churn through that quota in a day, silently deleting the caches you were counting on.

Saves that fail: immutable entries and key conflicts

Cache entries are immutable. When two parallel jobs race to save the same key, one wins and the other logs a reserve/already-exists failure; when a completed key already exists from an earlier run, the save is skipped. That is harmless noise if the entries are equivalent - and a design smell if you were relying on the same key being overwritten with fresher content. A key should uniquely describe its contents:

  • Derive keys from content hashes (hashFiles over lockfiles or source globs), never a static string you expect to mutate.
  • For accumulating caches, put something run-specific in the key and rely on restore-keys to find the nearest previous entry.

Old versions stop working

GitHub shut down the legacy cache service backend in early 2025. Workflows pinned to old tags of actions/cache (and old toolchain actions that cache internally) fail against the new service with errors that look like infrastructure problems rather than what they are: a version pin that aged out. The fix is mechanical - bump to the current major listed in the actions/cache README everywhere, including composite actions and reusable workflows that wrap it. If a workflow that "never changed" started failing on save or restore, check the pinned version before debugging anything else.

The failure mode with no error at all

The most expensive actions/cache problem produces green checkmarks: the cache restores, the log says hit, and the job is still slow - because a restore-then-verify cycle only saves the download, not the work. actions/cache caches files; it does not know which build steps could have been skipped. Compilation, tests, and lint re-run from scratch on every runner no matter how warm the dependency cache is. That second class of caching - skipping the work itself, keyed on the inputs that produced it - is a task-level remote cache, and it composes with actions/cache rather than replacing it: dependencies restore from the Actions cache, task outputs restore from the build cache. Where the line sits and how the two combine in a real workflow is the subject of our GitHub Actions cache guide.

Quick reference

  • Path Validation Error - no matching paths at save time; check the actual cache location, step order, and cleanup.
  • Permission denied - root-owned files from container or sudo steps; cache user-writable paths, or chown before restore/save.
  • "Cache not found" - branch scoping: only same branch, PR base, or default branch; warm shared caches from the default branch.
  • Vanishing entries - 7-day unused eviction and the repository quota; fat entries churn the quota fastest.
  • Failed saves - entries are immutable; make keys content-addressed with hashFiles.
  • Sudden failures on old workflows - the legacy service shutdown; bump the action version.
  • Green but slow - dependency caching cannot skip work; that is a job for a task-level remote cache.
Read the full guideGitHub Actions cache guideactions/cache vs artifacts vs a task-level remote build cache in CI.

Related posts

Put a shared build cache behind your builds
Free tier, no credit card - connect Nx, Turborepo, Gradle, or Bazel in about five minutes.
Start freeSee pricing