Debug-action-cache Guide

If you see Validation: SHA256 mismatch , your cache is corrupted (rare, but happens with network proxies). The solution is to delete the cache key.

To follow along, ensure you have:

The fastest way to look under the hood of your cache runner is to turn on advanced telemetry logs. On major platforms, this is triggered via specific environment variables or repository secrets. debug-action-cache

As of mid-2026, GitHub has released (beta) which introduces:

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). If you see Validation: SHA256 mismatch , your

Don't wait for the cache to break. Create a dedicated "Cache Debug" workflow in your repo ( .github/workflows/cache-debug.yml ):

- name: Inspect node_modules run: | du -sh node_modules ls -la node_modules | head -20 On major platforms, this is triggered via specific

: You will see Cache not found for input keys: .

| 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 - |

Using debug-action-cache to find the exact key to delete: