| Tool | Purpose | |------|---------| | ACTIONS_RUNNER_DEBUG=true | Full runner logs | | ACTIONS_STEP_DEBUG=true | Step-level cache logs | | gh api /repos/.../actions/caches | List existing caches | | restore-keys with wildcard | Catch similar caches | | lookup-only: true | Test restore without saving |
Do not cache huge, easily retrievable artifacts. Stick to package manager stores ( .npm , .cargo/registry , .gradle/caches ).
To prevent the need for intense debugging sessions in the future, build your workflows with these defensive caching strategies:
Usually a hash of a lockfile, like package-lock.json , Cargo.lock , or go.sum . debug-action-cache
To view a complete list of all saved caches, their sizes, their creation times, and their explicit keys, run:
If the hash doesn't change when you update dependencies, the cache won't invalidate. 3. Inspect Cache Contents Locally Sometimes "cache hit: true" doesn't mean the files were restored. You can use the GitHub CLI gh-actions-cache extension
The most powerful debug-action-cache technique is to store a .checksum file inside the cache. To view a complete list of all saved
key: $ runner.os -build-$ hashFiles('**/package-lock.json', '**/yarn.lock') Use code with caution. Issue C: Cache Eviction and Storage Limits Caches disappear randomly after a few days.
CACHE_PATH="$1" EXPECTED_HASH="$2"
A "dry-run" restoration mode that compares the restored cache against a fresh installation to identify drift. You can use the GitHub CLI gh-actions-cache extension
Are you experiencing (slow builds) or poisoned cache hits (stale/broken artifacts)?
What or unexpected behavior are you seeing in your workflow log?
A debug-action-cache log says:
If the package-lock.json file changes by even a single character, the generated hash changes, causing a . The pipeline then runs from scratch and saves a new cache entry. Common Symptoms of Cache Failures