cypress cannot find module after upgrade: how to fix

TL;DR

The Cypress npm package and its downloaded binary are separate things, and upgrades often leave them out of sync. Verify the binary, clear the cache, and reinstall. Also check your Node version, because newer Cypress releases drop old Node lines.

Error

Error: Cannot find module 'cypress'
Require stack:
- [HOME]/...

Steps

1. Run npx cypress verify. Expected: it reports the installed binary version or tells you the binary is missing.
2. If the binary is missing or mismatched, clear the cache and reinstall:

npx cypress cache clear
npm install
npx cypress install --force

Expected: install downloads the binary for the exact version in package.json.

1. Check node --version against the Cypress release notes. Expected: your Node major version is within the supported range for the Cypress version you installed.
2. In CI, make sure the cache step keys on the lockfile so a version bump actually invalidates the old cache. Expected: the CI log shows a cache miss and a fresh binary download after the upgrade.
3. Delete node_modules and reinstall from scratch if the error persists. Expected: npx cypress verify passes.

When to use

• Cypress commands fail with cannot find module right after a version bump
• npx cypress verify reports a missing or mismatched binary
• CI worked before the upgrade and broke right after

When not to use

• Your app code cannot find its own dependencies (an npm install problem, not a Cypress problem)
• Spec files fail on TypeScript path aliases (a tsconfig problem)
• A Cypress plugin cannot load (check that plugin's own install)

Tool compatibility

• Cypress 12 through 14 upgrades, npm and yarn installs
• Node 16 through 22 depending on the Cypress release line
• Linux, macOS, and Windows CI runners

Variant phrasings

Cypress binary not found after npm install

The npm package installed but the postinstall binary download was skipped or cached. Run npx cypress install directly.

Cannot find module cypress after upgrading to Cypress 13

Cypress 13 raised its Node floor. An old Node version can leave the install half finished.

Why it happens

Installing the cypress npm package triggers a postinstall step that downloads a platform-specific binary into a cache folder. Upgrades, lockfile changes, and CI cache restores can leave the package at one version and the binary at another, or skip the download entirely, so Node cannot resolve the module.

Edge cases

• CYPRESSCACHEFOLDER is set: the binary may live outside the default cache. Clear that folder instead.
• Corporate proxy blocks the download: the install fails silently. Set the proxy for the download step or pre-seed the cache.
• Works for teammates but not you: your local cache is stale. npx cypress cache clear fixes it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_XH95kPx-oEJmbm0U6fe5fA