Debug-action-cache
Enter the niche but powerful workflow debugging tool: . This isn't just a command; it is a mindset and a technical methodology for introspecting one of the most opaque parts of GitHub’s ecosystem.
[debug] Using key: 'build-cache-$ github.sha ' [debug] Cache created on: windows-2022 On Linux:
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-action-cache
In the world of modern DevOps, speed is currency. Every minute your Continuous Integration (CI) pipeline runs costs money and slows down developer feedback loops. GitHub Actions introduced caching to solve this—storing dependencies like node_modules , pip , or apt packages to avoid re-downloading them on every run.
Once set, re-run your workflow. You will see logs prefixed with [debug] inside the cache step. A normal log says: Cache restored from key: Linux-node-abc123 Enter the niche but powerful workflow debugging tool:
jobs: debug-cache: runs-on: ubuntu-latest env: ACTIONS_STEP_DEBUG: $ 'false' ACTIONS_RUNNER_DEBUG: ${} steps: - uses: actions/checkout@v4
The typical workflow looks like this:
| 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?