| Symptom | Likely Cause | Debug Action | |--------|--------------|---------------| | Cache always misses | Dynamic key includes timestamp or commit SHA | Print key value in logs; remove non-deterministic parts | | Restore succeeds but build fails | Cache contains platform-specific binaries (e.g., Linux binaries on macOS) | Check runner.os in key; separate caches per OS | | Cache too large | Unnecessary files (logs, temp, downloads) | Exclude them via paths or use tar --exclude | | Cache not deleted after PR merge | No automated cleanup | Use actions/cache with save-always: false or set a TTL via API | | Cache restore slow | Many small files or deep nesting | Cache archives (e.g., .tar.zst ) instead of directories |
(Select or describe)
Add to your workflow file:
Your hashFiles('requirements.txt') changed (maybe a whitespace change), causing the exact key to miss. The restore key Linux-pip- matched a cache from the staging branch instead of main . debug-action-cache
[debug] Using key: 'build-cache-$ github.sha ' [debug] Cache created on: windows-2022
Locate the section in the left sidebar and click Caches .
to list and even delete problematic caches from your terminal. 4. Live Debugging on the Runner | Symptom | Likely Cause | Debug Action
If you suspect the cache is corrupted or causing flaky builds, perform an isolation test.
This forces the cache engine to print exact compression statistics, network download speeds, and key-matching logic directly into the console. Step 2: Audit Cache Key Hashes
When your CI/CD pipeline starts acting like a "black box"—specifically when GitHub Actions or similar platforms aren't picking up new dependencies or are restoring corrupted environments—you’ve hit a cache invalidation nightmare. "Debug-action-cache" isn't just a task; it's a deep dive into how your build environment remembers the past. 1. The "Ghost in the Machine" Syndrome The most common reason to debug an action cache is a poisoned cache to list and even delete problematic caches from
It typically involves:
The most powerful weapon in your debugging arsenal is GitHub's built-in debug logging. When a workflow fails and the standard logs are insufficient, you can enable two levels of additional diagnostic information:
