GitHub Actions cache restore-keys not matching prefix

By Daniel Zoghalchali·Latchkey

restore-keys must be true prefixes of previously saved keys; if their structure differs from the primary key, no partial match is found and every miss falls all the way through to a cold cache.

What this error means

Even with restore-keys configured, the cache step still misses completely instead of restoring a recent partial entry.

Cache not found for input keys: Linux-node-3f2a1b, npm-cache-
(restore-key 'npm-cache-' is not a prefix of any saved key)

Common causes

restore-keys not a prefix of the primary key

The restore-key uses a different leading structure than the primary key, so it can never prefix-match a saved entry.

Prefix too specific

The restore-key is so close to the full key that nothing older falls under it, giving no partial hit.

How to fix it

Align prefixes with the primary key

1. Make each restore-key a leading substring of the primary key.
2. Order restore-keys from most to least specific.
3. Keep at least one broad prefix for any prior entry.

key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
  ${{ runner.os }}-node-
  ${{ runner.os }}-

How to prevent it

• Build restore-keys as true prefixes of the primary key.
• Order them most-specific to least-specific.
• Verify a partial hit occurs after a key change.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions