Dependency Caching, Cache Keys, Restore Strategies, and Performance: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first diagnostic sequence

Before rerunning or deleting a cache, preserve the run ID/attempt, event/ref/SHA, workflow revision, expanded cache key, restore-key list, cache-hit, cache ID/version/ref/size, runner/toolchain and the first failing dependency/build log. Then determine whether the failure belongs to key selection, scope/version matching, cache contents, package-manager reconciliation, runner/toolchain, network or the application itself.

This ordering matters because a rerun can create or access a different cache and make the original cause harder to prove.

2. Failure A — key omits the lockfile/toolchain/OS

A key such as dependencies is stable precisely when the dependency contract changes. An exact hit under that key is misleading: it proves only that the stale key exists.

# Broken: different lockfiles/toolchains collapse into one exact key.
- id: cache
  uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9
  with:
    path: ${{ steps.pip.outputs.cache_dir }}
    key: dependencies

Repair by deriving the exact key from the dimensions that can change cached bytes. Preserve the old key and failing run in the incident note; do not rewrite history by only showing the repaired run.

3. Failure B — cache contains secrets or trust-sensitive executable state

If a cache path includes credentials, private configuration or executable hooks from a low-trust workflow, treat it as a potential credential/data exposure or poisoning incident. Stop relying on the entry, rotate/revoke any exposed credentials, preserve exact cache identity and audit which refs could restore it. Masking has no effect on bytes inside the cache.

Do not “fix” this by encrypting a secret with a key stored in the same workflow. Sensitive data belongs in the appropriate secret system and should not be cached.

4. Failure C — using cache-hit as proof that installation can be skipped

This intentionally broken example caches pip's download store, then skips dependency installation on an exact hit. The first run may succeed because it installs packages; the next fresh runner gets an exact cache hit but no installed environment, so application import fails.

- id: cache
  uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9
  with:
    path: ${{ steps.pip.outputs.cache_dir }}
    key: pip-${{ runner.os }}-${{ steps.lock.outputs.sha256 }}

# Broken for a download cache: a hit does not populate .lab-site.
- name: Install dependencies
  if: steps.cache.outputs.cache-hit != 'true'
  run: python -m pip install --target .lab-site -r requirements.lock

- name: Verify fresh-runner environment
  run: PYTHONPATH="$PWD/.lab-site" python -S -c 'import idna'

5. Failure D — overly broad restore key

A restore prefix such as pip- can select entries from an incompatible Python version or architecture if the scope/version permits it. The action log may show a successful restore and cache-hit=false, yet the restored state can be useless or risky.

Repair by narrowing restore prefixes to compatibility boundaries such as OS/architecture/toolchain, or remove fallback entirely when consumers cannot safely reconcile stale state.

6. Failure E — generated build output hides environment dependence

A cached generated directory can depend on flags or SDKs that never appear in the key. Symptoms include intermittent test failures, binaries that differ from clean builds or machine-specific absolute paths. Compare a clean-cache build with the cached build and record toolchain/configuration digests before deciding the cache service is corrupt.

7. Failure F — stale self-hosted runner or cache action runtime

Current actions/cache v6 runs on Node 24. A self-hosted runner that cannot execute current Node 24 actions fails before cache semantics are even relevant. Preserve runner version and action SHA, update the disposable/staged runner, and rerun the smallest equivalent scope. Do not pin an obsolete insecure cache action indefinitely as the “fix.”

8. Reconcile workflow logs with cache-service metadata

GH_REPO='OWNER/gha-cache-lab'

# Read-only evidence. Filter the output locally by exact key/ref from the failed run.
gh api   -H 'X-GitHub-Api-Version: 2026-03-10'   "repos/$GH_REPO/actions/caches?per_page=100"   --jq '.actions_caches[] | {id,ref,key,version,size_in_bytes,created_at,last_accessed_at}'

Use the metadata to answer: Did an entry exist? Was it in the expected ref scope? Did its version match the requested path/archive format? Was the entry old or unexpectedly large? Only then decide whether to bypass, re-key or delete it.

9. Least-destructive repair order

1. Preserve first-failure logs and cache metadata.
2. Prove a clean-cache run can reconstruct dependencies.
3. Fix the key or restore strategy if it omitted correctness inputs.
4. Fix consumer behavior so restored state is validated/reconciled.
5. Rotate credentials if sensitive content entered a cache.
6. Delete only exact poisoned/stale lab entries after evidence is retained.
7. Rerun the smallest equivalent workflow and compare source SHA, key, hit state and output.

Knowledge check

Official references and version notes

• GitHub Docs — Dependency caching — cache purpose, artifact distinction and cache-security boundary.
• GitHub Docs — Dependency caching reference — key matching, restore keys, branch scope, versioning, limits and eviction.
• GitHub Docs — Managing caches — read-only inspection and exact cache deletion.
• actions/cache v6.1.0 — explicit cache action pinned to 55cc8345863c7cc4c66a329aec7e433d2d1c52a9.
• actions/setup-python v7.0.0 — Python setup action pinned to 5fda3b95a4ea91299a34e894583c3862153e4b97.
• setup-python dependency caching — built-in pip/pipenv/Poetry caching and cache-dependency-path.