Cypress says the npm package is installed but the binary is missing
The cypress npm package is installed, but the Cypress binary is missing.Short answer
The npm package is only a launcher. The Cypress binary is downloaded by an install script into a cache folder. It goes missing when install scripts are skipped, when the download was turned off, or when the cache folder differs between install and run. Print the cache path and reinstall the binary.
Fix it fast
1Find out which cause you have
Ask Cypress where it looks for the binary and which versions are there. Do this in the same job and user that runs the tests.
npx cypress cache path npx cypress cache list2Match what you see, then jump to its fix
- 1
The install used --ignore-scripts, or npm is configured with ignore-scripts=trueInstall scripts were skipped, so nothing downloaded the binaryFix - 2
The variable exists in the CI settings, Dockerfile or imageCYPRESS_INSTALL_BINARY=0 is set in the environmentFix - 3
Install works, but a later stage, user or container looks in a different folderThe binary cache folder differs between install and testFix
- 1
What does the error look like?
The cypress npm package is installed, but the Cypress binary is missing.Cypress binary is missing after npm install in CI or in a Docker build
Cause 1 of 3
Install scripts were skipped, so nothing downloaded the binary
1Check
Cypress downloads its binary from a postinstall hook. If the hook is skipped for any reason, the binary is missing unless it was already cached. npm does not run package scripts when ignore-scripts is true.
npm config get ignore-scripts2Fix
Install the binary explicitly after the dependency install.
npm ci --ignore-scripts
npx cypress install3Verify
The version is listed, and the binary starts.
npx cypress cache list
npx cypress verifyConfirmed by docs.cypress.io
Cause 2 of 3
CYPRESS_INSTALL_BINARY=0 is set in the environment
1Check
A value of 0 tells the install step to skip the binary download entirely.
env | grep CYPRESS2Fix
Unset it for the install, or install the binary yourself after the packages.
unset CYPRESS_INSTALL_BINARY
npm ci3Verify
The cache list shows the version.
npx cypress cache listConfirmed by docs.cypress.io
Cause 3 of 3
The binary cache folder differs between install and test
1Check
On Linux the default cache is ~/.cache/Cypress, and CYPRESS_CACHE_FOLDER has to exist every time you launch Cypress. A multi-stage Docker build, a different user, or a CI cache that restored an older folder gives a different result.
echo "$HOME $CYPRESS_CACHE_FOLDER"
npx cypress cache path2Fix
Point both stages at one folder, and make CI cache that folder with a key that includes the lock file.
export CYPRESS_CACHE_FOLDER=/opt/cypress-cache
npx cypress install3Verify
The path is the same in every stage, and verify passes there.
npx cypress cache path
npx cypress verifyConfirmed by docs.cypress.io
How do I stop it coming back?
- Run npx cypress cache path in CI so the log always shows where the binary should be.
- Cache the Cypress binary folder, but do not cache node_modules across builds.
- Use an official cypress/included image if you want the binary baked into the image.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Servers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
Azure App Service on Linux restarts the container and the site never starts
The container restarts again and again and the site returns an application error
App Service sends a warmup request to the container and restarts it if no HTTP answer comes back in time.
5 causes, each with a fixServers
bcrypt_lib.node: invalid ELF header inside a Docker container
Error: /app/node_modules/bcrypt/lib/binding/napi-v3/bcrypt_lib.node: invalid ELF header
bcrypt is a compiled addon, so the file in node_modules only runs on the operating system it was installed on.
3 causes, each with a fixServers
cdk deploy fails in a GitLab job with spawnSync docker ENOENT
code: 'ENOENT'
ENOENT means the operating system found no docker program to run.
3 causes, each with a fix