Cypress CYPRESS_CACHE_FOLDER not restored / re-installs every run in CI

Cypress caches its binary in ~/.cache/Cypress unless CYPRESS_CACHE_FOLDER overrides it. When the cache action, install, and run steps disagree on that folder, Cypress downloads the binary on every run or reports it missing.

What this error means

CI downloads the Cypress binary on each run despite an actions/cache step, or the run says the binary is not installed while a cache hit was reported. The cache path and CYPRESS_CACHE_FOLDER differ.

Cache restored from key: cypress-abc123
...
No version of Cypress is installed in: /home/runner/work/app/.cypress-cache/13.9.0
The cached folder was ~/.cache/Cypress, which the run step does not read.

Common causes

The env var and the cache path disagree

The cache saves ~/.cache/Cypress but the run exports a project-local CYPRESS_CACHE_FOLDER, so the restore is in the wrong place.

The variable is set for one step only

Install exports CYPRESS_CACHE_FOLDER but the run does not (or vice versa), so they resolve different folders.

How to fix it

Set one cache folder at job level and cache it

Define CYPRESS_CACHE_FOLDER once so install, cache, and run all agree.

env:
  CYPRESS_CACHE_FOLDER: ${{ github.workspace }}/.cypress-cache
steps:
  - uses: actions/cache@v4
    with:
      path: ${{ github.workspace }}/.cypress-cache
      key: cypress-${{ hashFiles('package-lock.json') }}

Or cache the default folder

If you do not override it, cache ~/.cache/Cypress so restores match runs.

- uses: actions/cache@v4
  with:
    path: ~/.cache/Cypress
    key: cypress-${{ hashFiles('package-lock.json') }}

How to prevent it

• Define CYPRESS_CACHE_FOLDER at job level so every step is consistent.
• Point the cache path at the exact folder Cypress installs into.
• Key the cache on the lockfile so a Cypress bump refreshes the binary.

Related guides