Debug-action-cache

You run a Windows runner and a Linux runner. They share the same cache key. Debug logs reveal:

[debug] Using key: 'build-cache-$ github.sha '
[debug] Cache created on: windows-2022

On Linux:

[debug] Restoring cache... (originally saved on windows-2022)
[debug] Extracting binary: 'app.exe' -> incompatible.

The debug log doesn't warn you about OS mismatch, but it gives you the metadata (runner OS) if you scroll up to the "Created on" line. This tells you to add runner.os to your key.

Let's simulate a broken pipeline. You have a monorepo with Python and Node.js. Your Python cache keeps restoring a 3-month-old virtual environment. debug-action-cache

Cache saves happen in the post phase of the action. Most developers miss these logs. To capture them:

- name: Save cache manually (debug mode)
  if: always()
  uses: actions/cache/save@v3
  with:
    path: node_modules
    key: $ runner.os -node-$ hashFiles('package-lock.json') -debug

This isolates the save logic, allowing you to see errors like Cache size of 11.2 GB exceeds limit of 10 GB.

The Debug Action Cache offers several benefits, including: You run a Windows runner and a Linux runner

A common mistake is mis-specifying the path. The debug log will show exactly what is being archived:

[debug] Resolved path: 'node_modules' -> '/home/runner/work/app/node_modules'
[debug] Path exists: true
[debug] Contents: [ 'react', 'lodash', '.bin' ]

If you see Path exists: false, you know your working directory is wrong. Add working-directory: ./app to your step.

You do not add a new YAML step. Instead, you set a secret in your repository: On Linux: [debug] Restoring cache

Note: Some advanced users also set RUNNER_TOOL_CACHE_DEBUG to true, but ACTIONS_STEP_DEBUG triggers the specific debug-action-cache protocol.

Once set, re-run your workflow. You will see logs prefixed with [debug] inside the cache step.