Here’s an interesting, practical guide to understanding and debugging GitHub Actions cache behavior — specifically focusing on the actions/cache step and common "cache not restored" or "cache save failed" issues.
If you find a corrupted cache, you cannot edit it. You must delete it. GitHub does not have a UI for deleting individual caches (as of 2025), but you can use the gh CLI or the delete-cache action.
Using debug-action-cache to find the exact key to delete:
Search the logs for: Cache restored from key:. Copy that key.
Then, in a workflow or locally:
gh actions cache delete <KEY> --repo <owner>/<repo>
Or use the community action actions/delete-cache with that exact key.
Problem: Cache restored only 20% of the time.
Logs show: Cache not found for key: linux-npm-xyz123
Check key generation:
- name: Debug cache key
run: |
echo "key: $ runner.os -npm-$ hashFiles('**/package-lock.json') "
ls -la **/package-lock.json
Output shows:
package-lock.json changes every build (e.g., due to npm install --package-lock-only differences).
Fix:
key: $ runner.os -npm-$ hashFiles('package-lock.json')
restore-keys: |
$ runner.os -npm-
Now even if exact key misses, it restores the most recent linux-npm-* cache.
The cache action creates a .tar archive. Debug logs reveal segmentation:
[debug] Compressing 1,234 files (245MB)
[debug] Archive segmented into 3 parts
[debug] Uploading part 1/3...
If you see a segmentation error (e.g., Part 2 failed to upload), you have a network issue or a file that changed during compression (race condition).
"debug-action-cache is a CI build cache that stores and restores action outputs keyed by inputs to speed repeat runs and aid debugging."
Would you like a different length or to tailor this for a specific CI system?
To debug a GitHub Actions cache and inspect its solid content, you can use several methods ranging from built-in debug modes to external CLI tools. 1. Enable Action Debug Logging debug-action-cache
The simplest way to see exactly what files are being cached is to enable Runner Debug Logging.
How-to: Go to your repository Settings > Secrets and variables > Actions and add a secret named ACTIONS_STEP_DEBUG with the value true.
Effect: The actions/cache logs will then list every file being saved to or restored from the cache during your workflow run. 2. Use the GitHub CLI (gh)
You can manage and inspect caches directly from your terminal using the GitHub CLI.
List Caches: Use gh cache list to see all current cache entries, their sizes, and creation times.
Delete Caches: If a cache contains "bad" content, remove it with gh cache delete . 3. Verify with Artifacts (Manual Inspection)
Because the cache is normally "invisible" (you can't browse it like a folder), a common "solid" debugging technique is to temporarily upload the cached directory as an Action Artifact. Workflow Step:
- name: Upload directory for inspection uses: actions/upload-artifact@v4 with: name: debug-cache-content path: path/to/your/cached/folder Use code with caution. Copied to clipboard Step 4: Forced Eviction If you find a
Why: This allows you to download a .zip of the exact folder contents to your local machine to verify the files are correct before they are saved to the cache. 4. Troubleshoot "False" Cache Hits
If your logs say "Cache restored successfully" but your tools still rebuild from scratch (a common "soft" vs "solid" content issue), check your hash keys.
Validation: Add a debug step to run ls -R on your cache path immediately after the restore step to see if the files actually exist.
Common Issue: Often, the cache-hit output is false because only a partial match was found via restore-keys, meaning the content isn't an exact match for your current dependencies. 5. Web Interface Management
GitHub now provides a native UI for cache oversight. You can navigate to the Actions tab in your repo and select Caches on the left sidebar to view a list of all entries and their metadata.
Caching not working · community · Discussion #163260 - GitHub
actions/cache in GitHub Actions involves enabling debug logging to inspect key generation, understanding that caches are immutable and branch-scoped, and addressing storage limits. Key troubleshooting steps include verifying
accuracy, checking paths, and managing cache keys to resolve cache misses or failed restorations. For detailed guidance, consult the GitHub Actions Caching Documentation Dependency caching reference - GitHub Docs Or use the community action actions/delete-cache with that