cypress github actions cache not hitting: how to fix

TL;DR

A Cypress cache miss is almost always a changed cache key, a wrong cache path, or the install running after the restore step. The binary lives in the Cypress cache directory (usually under the home folder), and the key must hash a stable lockfile. Fix the key and the ordering first; those two cover most misses.

The query

cypress github actions cache not hitting: how to fix

Use this when

• CI logs show Cypress downloading the binary on every run
• Cache restore logs say "cache not found" for a key you expected to hit
• You recently changed the workflow file or the Node version

Not for

• Caching node_modules or pnpm stores (separate cache, separate key)
• Cypress Docker image pulls
• Test result or artifact caching

Steps

1. Read the restore log for the exact key tried. The log prints the key it looked up and the keys it fell back to. Copy the attempted key.

Expected output: the literal cache key from the log, for example a key containing the lockfile hash and runner OS.

1. Check the key is stable. The key should hash your lockfile and include the OS and Cypress version. If it includes a timestamp, branch name, or run id, every run gets a fresh key.

Expected output: a key definition with no volatile inputs, confirmed by comparing keys across two runs.

1. Verify the cached path. The path must point at the Cypress binary cache directory. Print the cache folder location in a debug step and compare it to the path in the cache action.

Expected output: the debug step prints the same directory the cache action restores.

1. Fix the step order. The cache restore must run before the Cypress install step, and the save happens automatically after. If install runs first, the binary downloads before the cache is ever consulted.

Expected output: a workflow where restore precedes install, with a log line showing the binary found in cache.

1. Add restore-keys as a fallback. A prefix restore-key lets a slightly older cache hit instead of a full cold download.

Expected output: partial cache hits in the log on runs where the exact key misses.

1. Confirm with a clean run. Push a trivial commit and check that the binary is not downloaded.

Expected output: CI logs showing cache hit and no Cypress download step.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_9aUQV95N5i069fkJMXMY2w