In this 2,500+ word guide, we will dissect the anatomy of action caching, explore why debugging is necessary, and provide a step-by-step playbook to master debug-action-cache . Before we debug, we must understand the problem. GitHub Actions cache is an immutable blob storage system. You write a cache using actions/cache@v3 or v4 , and later, you attempt to restore it using a key.
[debug] Download speed: 45.2 MB/s [debug] Parallel chunks: 4 [debug] Validation: SHA256 matches expected If you see Validation: SHA256 mismatch , your cache is corrupted (rare, but happens with network proxies). The solution is to delete the cache key. Let's map error symptoms to debug-action-cache insights. debug-action-cache
| Symptom | Debug Log Evidence | Fix | | :--- | :--- | :--- | | Cache never restores | GET response: 404 for all keys | Check hashFiles glob pattern. Use ls before cache step to ensure file exists. | | Cache restores empty folder | Path '/cache/node_modules' does not exist | Your path is relative. Use absolute path or $ github.workspace /node_modules . | | Cache upload takes 20 minutes | Compressing 50,000 files | You are caching temporary files (e.g., __pycache__ ). Add !**/__pycache__ to exclude. | | Cache uses too much space | Cache size: 11.2GB (exceeds 10GB limit) | Split cache: One for node_modules , one for build . Use actions/cache/save conditionally. | | Random cache misses | restoreKeys: [ 'Linux-node-' ] matches Linux-node-stable | Make your restore-keys more specific, e.g., $ runner.os -node-$ github.ref - | The debug-action-cache flag is great for real-time runs. But what if the workflow succeeded three days ago and you want to see what was cached? In this 2,500+ word guide, we will dissect