Debug-action-cache May 2026
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
To debug a GitHub Actions cache issue, the most direct method is to enable Step Debug Logging. This reveals detailed cache keys, hit/miss logs, and download URLs in your workflow run. 🛠️ Essential Debugging Steps debug-action-cache
Enable Debug Logs: Create a repository secret named ACTIONS_STEP_DEBUG with the value true.
Verify Cache Keys: Check the hashFiles output in logs to ensure your lockfiles (e.g., package-lock.json) are being picked up correctly. Common Problems & Solutions | Symptom | Likely
Check Management UI: Go to Settings > Actions > Caches in your repository to see total size and individual keys.
Isolate Save/Restore: Use actions/cache/restore and actions/cache/save as separate steps to identify if the failure is during download or upload. 📊 Sample Debug Report Data but merging to main causes failures.
When debug logging is enabled, your Action logs will include these specific markers: Description ##[debug]Resolved Keys: Shows the actual string used to find existing caches. ##[debug]Cache service version: Identifies the API version (e.g., v2).
Common Problems & Solutions
| 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 |
7. Prevention / Recommendations
- Enable debug logging permanently for cache troubleshooting in a separate workflow.
- Use cache version prefix (e.g.,
v1-...) to allow manual invalidation. - Regularly audit cache size with
gh cache list --repo <repo>. - For self-hosted runners, configure an external cache backend (e.g.,
@actions/cachewith Azure Blob).
2. Common Caching Issues (The "Why")
Before debugging, identify which of these scenarios fits your problem:
- Cache Miss: The workflow runs, but it re-downloads dependencies every time.
- Cause: The key changes every run (e.g., including a timestamp or commit SHA in the key).
- Cache Not Saving: The job completes, but logs show "Cache not saved."
- Cause: The cache size exceeds the limit (currently 10GB per repository), or the path provided in the action does not exist.
- Stale Cache: Dependencies update, but the workflow uses old versions.
- Cause: The key generation logic (hash) didn't change when the dependency file changed, or
restore-keysmatched an old cache too aggressively.
- Cause: The key generation logic (hash) didn't change when the dependency file changed, or
- Cross-Branch Pollution: A feature branch works fine, but merging to main causes failures.