Debug-action-cache

The Debug Action Cache can be implemented using a variety of techniques, including:

| Step | Command / Action | Result | |------|------------------|--------| | Enable debug logs | Set secret ACTIONS_RUNNER_DEBUG to true | ✅ / ❌ | | List cache entries | gh actions-cache list --limit 50 | Shows: <list keys> | | Check exact key used | Log $ hashFiles('package-lock.json') | Value: <hash> | | Verify path exists | ls -la ~/.npm before save | ✅ / ❌ | | Check cache size | du -sh <path> | Size: <MB> (< 10GB?) | | Test exact key restore | Manual restore using key only | Works / Fails |

The Debug Action Cache is a caching layer that stores the results of debug actions, which are computational tasks executed during the debugging process. The cache is typically used to store the results of: debug-action-cache

A common silent failure is the cache action looking for a directory that doesn't exist yet, or has different permissions than expected.

- name: Debug directory structure
  run: |
    echo "Checking if path exists..."
    if [ -d "node_modules" ]; then
      echo "Directory exists."
      ls -la node_modules | head -n 20
    else
      echo "Directory DOES NOT exist."
    fi

| Problem | Likely cause | Debug check | |--------|--------------|--------------| | Cache miss every run | Key includes github.sha or github.run_id | Log the key — is it changing? | | Cache saved every run | Key too specific + no restore-keys | Add a broader restore-keys | | Cache too large (>10 GB) | Unnecessary files | List cached dir content in debug mode | | Cache not restored on pull_request | Different branch base | Use restore-keys without branch hash | The Debug Action Cache can be implemented using

You do not add a new YAML step. Instead, you set a secret in your repository:

Note: Some advanced users also set RUNNER_TOOL_CACHE_DEBUG to true, but ACTIONS_STEP_DEBUG triggers the specific debug-action-cache protocol. - name: Debug directory structure run: | echo

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

There is no single "debug-action-cache" button, but you can implement the following strategies to investigate issues.