Resource library

QA How-To

How to Fix "Cypress failed to start" and cypress verify Errors

Fix Cypress failed to start and cypress verify errors by diagnosing missing binaries, Linux libraries, cache permissions, timeouts, proxies, and CI setup.

18 min read | 3,332 words

TL;DR

Run npx cypress version and npx cypress cache list. Install a missing binary with npx cypress install, then run npx cypress verify; if it still fails, use DEBUG=cypress:cli* to identify the underlying library, display, permission, timeout, or download error.

Key Takeaways

  • Use the line below the startup headline to classify the actual failure.
  • Check the npm package and cached Cypress application separately.
  • Run cypress install and cypress verify in the same environment and user session.
  • Use ldd and the official package list for missing Linux shared libraries.
  • Repair CI cache, display, permission, and network problems at their own layer.
  • Verify one real spec after the Cypress smoke check passes.

To fix Cypress failed to start when cypress verify, cypress open, or cypress run launches the desktop binary, read the error immediately below that headline. The remedy depends on whether the application is absent, a Linux library cannot load, the display is unavailable, or the process cannot execute.

Cypress failed to start.

This guide gives a quick recovery path, then a command to identify and verify each root cause. Run the examples from the project root, where Cypress is declared in package.json. The examples use npm; keep your project's existing package manager and lockfile. If the binary verifies but a browser or test fails later, diagnose that separate stage after this launch check passes.

TL;DR

Run npx cypress version and npx cypress cache list. If the package exists but its matching binary is absent, run npx cypress install, then npx cypress verify. If a cached binary still cannot start, run DEBUG=cypress:cli* npx cypress verify and follow the first specific cause printed after the launch failure. On Linux, inspect shared libraries and the display before clearing the cache.

npm ci
npx cypress version
npx cypress cache list
npx cypress install
npx cypress verify

A successful last command reports Verified Cypress!. An install failure caused by a blocked download requires network or certificate repair; repeating the same install command will not change that. Cypress documents the installation controls and CLI commands.

What the Error Actually Means

The npm cypress package and the Cypress desktop application are separate artifacts. The package in node_modules supplies the CLI and types. Installation downloads the platform-specific application into a cache outside the project. cypress verify locates that binary and launches it for a smoke check. A passing npm ci does not, by itself, prove that the desktop process can execute.

Cypress failed to start. is a wrapper, not a diagnosis. The following lines may reveal ENOENT, EACCES, a missing .so library, a display failure, or a timeout. Preserve those lines when reporting the problem. Also distinguish cypress verify from a failed cy.visit(): verification happens before test code, while a page error happens after a browser and spec have started. For runner setup from scratch, see the Cypress tutorial for beginners.

Start with a small, reproducible observation:

node --version
npm --version
npm ls cypress --depth=0
npx cypress version
DEBUG=cypress:cli* npx cypress verify

The first commands establish the runtime and locally installed Cypress package. cypress version prints package and binary versions when available. The debug run shows the cache path and launch sequence. Save its full output privately when comparing CI machines; check for sensitive paths and proxy details before sharing logs publicly.

Root-Cause Decision Table

Symptom near cypress verify Likely root cause Targeted fix
Cached binary cannot be found Install script skipped or cache lost Run npx cypress install in the failing environment
Package and binary versions differ Stale cache or CYPRESS_RUN_BINARY override Inspect versions and restore a matching binary
error while loading shared libraries Missing Linux OS package Find the missing .so with ldd and install the prerequisite
Display connection error No usable X server Install and use Xvfb, or choose a suitable CI image
EACCES or EPERM Cache directory or executable permissions Use a writable cache with a consistent user
Verification times out Slow startup or overloaded runner Check resources, then adjust CYPRESS_VERIFY_TIMEOUT if justified
Download or certificate error Proxy, firewall, or private CA Configure trusted access to Cypress download hosts
Works locally, fails in Docker or CI Different OS, architecture, user, or cache lifecycle Install and verify inside the actual runner image

Use the table as a branch selector. A cache reset can repair a damaged binary, but it will not install libnss3 or start a display server. Each numbered section ends with a check that should pass before moving on.

1. Fix Cypress Failed to Start When the Binary Is Missing

Ask the CLI which binary it sees. npm ls confirms that the package exists; cypress cache list confirms that an application is cached. These answer different questions. A project may have a valid lockfile and populated node_modules but no Cypress application if lifecycle scripts were disabled or a CI cache restored only JavaScript packages.

npm ls cypress --depth=0
npx cypress cache path
npx cypress cache list
npx cypress version

If the expected binary is missing, run the install step explicitly. Cypress installs the binary matching the package in the current project. If this environment uses npm ci --ignore-scripts, that option suppresses the postinstall download; an explicit Cypress install must follow. Check CI configuration for CYPRESS_INSTALL_BINARY=0 too. That setting intentionally skips downloading and is useful only when a later step supplies the application.

npx cypress install
npx cypress verify

The second command is the per-step check: it should end with Verified Cypress!. If npx proposes downloading a package, stop and return to the project directory; you may be outside the repository that declares Cypress. Do not treat npm cache clean as a binary repair. npm's package cache and Cypress's application cache are different. Cypress describes this case as a cached binary that could not be found.

If download succeeds but verification still cannot find the application, compare npx cypress version with npx cypress cache list and inspect CYPRESS_CACHE_FOLDER in the current shell. CI install and test steps must point to the same cache location.

2. Fix Cypress Failed to Start With a Damaged or Mismatched Cache

An interrupted unzip, partial filesystem restore, or cache keyed too broadly can leave a folder that looks installed but cannot start. Compare package and binary versions before changing anything. cypress version prints them separately; cypress cache list shows cached application versions. An override through CYPRESS_RUN_BINARY can direct the CLI to a different executable.

npx cypress version
npx cypress cache list
printenv CYPRESS_RUN_BINARY
printenv CYPRESS_CACHE_FOLDER

If the matching version is cached but corrupted, force a fresh install for the current package. This overwrites its existing installation without deleting every cached version on a shared developer machine. It requires working download access and enough free disk space for the archive and extraction.

npx cypress install --force
npx cypress verify

If you intentionally set CYPRESS_RUN_BINARY, confirm that it points to the extracted Cypress executable, not a downloaded zip or directory. An override can make a healthy cache irrelevant. Unset it and verify again if you did not mean to use a custom binary.

unset CYPRESS_RUN_BINARY
npx cypress version
npx cypress verify

Use npx cypress cache clear only when the cache as a whole is unusable. It deletes all cached Cypress versions, so every project on that machine must reinstall its application. Run npx cypress install immediately afterward. The check is npx cypress verify, which exercises the binary rather than merely listing a folder. The Cypress CLI reference documents install --force and cache commands.

3. Repair Missing Linux Shared Libraries

On Linux, Cypress can exist on disk while the dynamic loader refuses to start it. A message such as error while loading shared libraries: libnss3.so: cannot open shared object file points to the host image, not a JavaScript dependency. Cypress's smoke test reports the missing library; ldd can confirm unresolved libraries on the exact cached executable.

CYPRESS_DIR="$(npx cypress cache path)"
find "$CYPRESS_DIR" -path '*/Cypress/Cypress' -type f -print

Choose the path printed for the version your project uses, then supply it to ldd. The following command checks cached Linux executables and prints unresolved entries. On a shared cache, inspect the output for your package version rather than assuming every cached entry belongs to this project.

find "$(npx cypress cache path)" -path '*/Cypress/Cypress' -type f -exec ldd {} \; | grep 'not found' || true

Install the operating-system prerequisites listed for your distribution in the official Cypress install guide. For an Ubuntu 24.04 runner, the documented package names include the t64 variants below. Other Ubuntu or Debian releases use different names, so match the command to the runner image.

sudo apt-get update
sudo apt-get install -y libgtk-3-0t64 libgbm-dev libnotify-dev libnss3 libxss1 libasound2t64 libxtst6 xauth xvfb
npx cypress verify

Verification must run in the same container or VM that failed. If ldd still prints not found, resolve those libraries before retrying cypress run. Installing npm packages named after a missing .so file cannot satisfy the OS loader. The Docker guide for QA testers explains the host and container dependency boundary.

4. Restore a Display Server for Linux Verification

The Cypress application uses a graphical stack even when you run tests headlessly. In a minimal Linux job, an absent display or Xvfb can stop the smoke test before any spec executes. Check whether DISPLAY is set and whether Xvfb is installed. A blank DISPLAY alone is not always fatal because Cypress can start Xvfb automatically; the debug log supplies the final evidence.

printenv DISPLAY
command -v Xvfb
DEBUG=cypress:cli* npx cypress verify

On Debian or Ubuntu, install xvfb and xauth if missing. If the runner has a conflicting or inaccessible display, launch verification under a fresh virtual display explicitly. xvfb-run is provided by the Xvfb package, and -a selects an available server number.

sudo apt-get update
sudo apt-get install -y xvfb xauth
xvfb-run -a npx cypress verify

A Verified Cypress! result here shows the binary and libraries work under a usable display. If ordinary npx cypress verify still fails, inspect the job's DISPLAY assignment and X socket permissions. Run xvfb-run -a npx cypress run as a diagnostic while repairing the job setup; do not stack multiple independently managed Xvfb servers in a permanent CI script. Official Cypress images already include Linux prerequisites and are often simpler than a minimal base image.

Browser selection is a later stage. A failure to launch Chrome after verification may concern Chrome or an enterprise policy, while cypress verify checks Cypress itself. See running Cypress tests in headed mode when you need to inspect a browser interactively.

5. Fix Cache Permissions and Unwritable Home Directories

An EACCES or EPERM in launch output means the effective user cannot read, execute, or update a path Cypress needs. This often appears when one CI step installs as root and a later step runs as a regular user, or when a container mounts a read-only home directory. Record the user, cache path, and directory ownership before modifying permissions.

id
CYPRESS_DIR="$(npx cypress cache path)"
printf '%s\n' "$CYPRESS_DIR"
ls -ld "$CYPRESS_DIR"
npx cypress verify

For a job with a writable workspace, put the Cypress cache under that workspace for both installation and execution. Set CYPRESS_CACHE_FOLDER before npm ci, and retain the same value for verify and run. The directory must exist when Cypress starts. This avoids changing ownership of a shared system cache.

export CYPRESS_CACHE_FOLDER="$PWD/.cache/Cypress"
mkdir -p "$CYPRESS_CACHE_FOLDER"
npx cypress install
npx cypress verify

Do not use chmod -R 777 on a shared machine. It hides the identity mismatch and grants unnecessary write access. If the existing cache belongs to another user, change the job so installation and execution use one account, then rebuild that account's cache. In Docker, check both the container user and bind-mounted file ownership. Cypress documents CYPRESS_CACHE_FOLDER as the supported way to relocate the binary cache.

For a deliberately read-only custom binary, Cypress supports CYPRESS_SKIP_VERIFY=true, but skipping the smoke test removes the check this guide is trying to restore. Use it only when you have already proved the executable launches and cannot permit verification metadata to be written.

6. Diagnose Verification Timeouts and Resource Pressure

A timeout differs from an immediate loader error. The binary may need longer to start on a busy CI runner, especially while a job unpacks dependencies or competes for CPU and memory. Check debug timestamps and system resources first. Cypress documents CYPRESS_VERIFY_TIMEOUT in milliseconds; its default is 30000. Increasing it is a targeted response to a measured slow launch, not a repair for an absent binary.

DEBUG=cypress:cli* npx cypress verify
df -h .
free -h
nproc

free and nproc are Linux commands; on macOS, inspect resource use with Activity Monitor or top. Look for disk exhaustion, a container memory limit, and competing parallel jobs. Cypress's install guidance recommends at least two CPUs and 4 GB RAM for CI, with more for long runs or video recording. If the runner is undersized, allocate resources before treating a longer timeout as permanent.

When startup genuinely takes longer on an otherwise healthy machine, try a bounded increase and compare elapsed time across repeated clean jobs:

CYPRESS_VERIFY_TIMEOUT=60000 npx cypress verify

The expected result is Verified Cypress! within the new limit. If the job later times out again, capture DEBUG=cypress:cli* output and investigate process state rather than repeatedly doubling the value. CYPRESS_VERIFY_TIMEOUT must also be present for cypress run or cypress open when those commands trigger verification. A CI test automation guide can help structure install, verify, and run gates so each failure has its own log.

7. Fix Proxy, Firewall, and Certificate Failures During Install

If cypress install cannot download the application, cypress verify cannot repair it. The CLI package may have arrived from a mirrored npm registry while the binary request to Cypress's download service is blocked. Inspect the install step with debug output and identify whether the failure is DNS, connection reset, proxy authentication, or certificate validation.

DEBUG=cypress:cli* npx cypress install
npx cypress cache list

Cypress identifies download.cypress.io and cdn.cypress.io as binary download hosts. On a corporate network, request access to those hosts or use an approved internal mirror. Set the system proxy for the installation process if your environment requires one; do not commit proxy credentials. Install a custom CA through your organization's supported Node and OS trust configuration rather than bypassing TLS validation.

If your team already hosts a compatible Cypress mirror, supply its URL at install time. The placeholder below represents an existing approved endpoint; it is not a public Cypress URL.

CYPRESS_DOWNLOAD_MIRROR=https://your-approved-mirror.example npx cypress install
npx cypress verify

Cypress also supports CYPRESS_INSTALL_BINARY for an approved local zip or direct URL, but that override must be supplied for each relevant install unless recorded in npm configuration. Do not choose a binary version different from the npm package merely to make a download complete. Verify both versions with npx cypress version after any custom install. The Cypress advanced installation guide lists proxy, mirror, and CA controls.

8. Make the Fix Work in CI and Docker

A local pass does not establish a CI pass if runners have different OS packages, CPU architecture, home directories, or cache contents. Put npm ci, binary installation if required, and npx cypress verify in the same execution environment. Cache the Cypress binary folder separately from npm's download cache. A restored node_modules tree alone can bypass the install script that normally downloads Cypress.

npm ci --foreground-scripts
npx cypress version
npx cypress verify
npx cypress run

Use --foreground-scripts while diagnosing an npm install so Cypress postinstall output is visible. Once stable, normal CI installation can follow your repository policy. A distinct verify step makes clear whether the runner failed before tests or during a spec. For workflow design, consult test automation in CI/CD.

For Docker, choose a published cypress/browsers image tag compatible with the Node and browser versions your project requires. Replace the placeholder with an actual tag from the Cypress image catalog; never assume a local host cache is inside the container. Run from a checkout containing package-lock.json and a Cypress dependency:

docker run --rm -v "$PWD":/e2e -w /e2e cypress/browsers:<matching-published-tag> sh -lc 'npm ci && npx cypress verify'

The command verifies inside the image, where Linux libraries and user permissions matter. If the image architecture differs from the host, select a supported image platform instead of copying an incompatible cached binary. Cypress also publishes cypress/included, which carries a fixed Cypress version; match that image tag to the project's installed package before using it.

When a Docker build installs as root and runtime starts as another user, keep the application cache where the runtime user can access it. For a fuller example, see writing a Dockerfile for test automation. GitHub Actions container jobs require Linux runners, as documented in the Cypress GitHub Actions guide.

How to Verify the Fix

Use a three-stage check. First, inspect npx cypress version and confirm package and binary versions agree. Second, run npx cypress verify in the same user session, container, and environment variables as the failing run. Third, execute a real spec to prove browser and application-under-test startup work.

npx cypress version
npx cypress verify
npx cypress run

A Verified Cypress! line confirms the application launched for the smoke check. It does not prove that your development server is reachable, Chrome is installed, or all tests pass. If verification succeeds but cypress run fails, follow the new error. A failed cy.visit() concerns server availability or networking; a browser crash concerns browser resources or launch configuration. Preserve command exit codes in CI rather than filtering output through a command that masks failure.

If the full suite is expensive, select an existing spec with the documented --spec flag:

npx cypress run --spec "cypress/e2e/smoke.cy.js"

Replace that path with a real file in your repository. This check succeeds only when Cypress launches, discovers the selected spec, and the spec passes. For test instability after startup, the Cypress flaky test guide covers retries and diagnosis.

Prevent It From Coming Back

Keep the Cypress package in the project lockfile and use the same lockfile-driven install locally and in CI. Make binary install and verify steps visible in job logs. If you cache the application, key it by operating system, architecture, and Cypress package version; otherwise a valid folder name can hide an incompatible executable. Cypress's performance guidance cautions that caching node_modules may bypass integrity checks and the binary download hook.

Keep host prerequisites in the runner image or a documented provisioning step. A test repository cannot supply missing libgtk libraries through package.json. In Docker, choose a published image with the required browsers and pin the selected tag in your real workflow after checking the catalog. Review that pin when the Cypress package or browser requirements change.

Run npx cypress verify immediately after installation, before starting the application. This gives a short, actionable failure instead of a later suite failure with mixed logs. Record cache path, package version, binary version, effective user, and runner image in failure reports. Avoid storing complete environment dumps or proxy credentials in public artifacts. If your team maintains a Cypress framework, include the launch gate in its setup documentation.

Interview Questions and Answers

Q: What does cypress verify prove? It launches the cached Cypress application for a smoke check. It does not execute test specs or check your application server.

Q: Why can npm ci succeed while Cypress cannot start? npm can install the CLI package while the separate binary download is skipped or its cache is unavailable. Check both artifacts with npm ls cypress and npx cypress version.

Q: What is the first Linux diagnostic after a library error? Run ldd on the cached executable and look for not found. Install the missing OS packages for that runner distribution.

Q: When is install --force appropriate? Use it when the matching cached binary exists but may be incomplete or corrupted. It refreshes that installation, while cache clear removes every cached version.

Q: Why can CI fail after local verification passes? CI may use another OS, architecture, user, display setup, or cache path. Verify in the actual runner instead of copying a local binary.

Q: Should a team set CYPRESS_SKIP_VERIFY=true to fix startup? Only for a deliberately read-only binary location after proving the executable works. Skipping verification conceals ordinary missing-dependency and permission failures.

For deeper hiring practice, review Cypress interview questions and answers.

Common Mistakes

  • Clearing the entire cache before reading the line after Cypress failed to start.. This discards evidence and forces downloads without installing missing Linux libraries.
  • Treating npm ls cypress as proof that the desktop application exists. The CLI package and cached executable have separate lifecycles.
  • Running a repair as root, then testing as a regular user. The new cache ownership can cause EACCES.
  • Setting CYPRESS_VERIFY_TIMEOUT for immediate ENOENT or shared-library errors. A timer cannot load an absent file.
  • Disabling TLS certificate checks to get a binary through a proxy. Configure approved trust or a mirror instead.
  • Copying a Cypress binary between macOS, Windows, Linux, or CPU architectures. Reinstall on the target platform.
  • Calling every cypress run failure a startup failure. After verification passes, inspect browser launch, app server, and spec output separately.

Conclusion

To fix Cypress failed to start, preserve the error below the headline and locate the failing layer. Install the matching cached binary, repair Linux libraries or display support, correct permissions, or fix download access as indicated. Then run npx cypress verify in the same environment that failed.

Keep verification as a separate CI gate and run one real spec after it passes. That sequence tells you whether the Cypress application, browser, and test environment are each ready.

Interview Questions and Answers

How would you triage Cypress failed to start in a new CI pipeline?

I would keep the complete verify log, then compare npm ls cypress, cypress version, and cypress cache list in the failing job. I would use DEBUG=cypress:cli* npx cypress verify to identify the first concrete failure. Only then would I change binary installation, OS prerequisites, permissions, or runner resources.

Why can a successful npm install still leave Cypress unusable?

The npm package contains the CLI, while the platform-specific application lives in a separate cache. A skipped postinstall, blocked download, or missing CI cache can leave the package present without a runnable binary. I would explicitly install and verify the binary in the same environment.

How do you distinguish a missing binary from a broken binary?

I compare cypress version with cypress cache list. A missing matching entry points to an install or cache lifecycle problem. If the matching entry exists but cannot execute, I inspect debug logs and consider install --force after ruling out host libraries and permissions.

What would you do with a libnss3.so error?

I would run ldd on the cached Cypress executable to confirm unresolved libraries. Then I would install the documented OS prerequisites for that Linux distribution in the runner image. Repeating npm install alone would not supply a system shared library.

How does Xvfb affect headless Cypress runs?

Cypress's desktop application still needs a graphical stack even for headless test execution. On Linux, Cypress may start Xvfb automatically, but a missing package or invalid DISPLAY can prevent verification. I would test with xvfb-run -a npx cypress verify and then repair the CI display setup.

When would you increase CYPRESS_VERIFY_TIMEOUT?

I would first establish that startup is slow, not failing immediately on a missing dependency. I would inspect runner CPU, memory, disk, and debug timestamps. If the host is healthy but startup exceeds the default limit, I would set a measured timeout for both verification and test execution.

What is the risk of caching node_modules in a Cypress pipeline?

A restored node_modules tree may bypass the postinstall step that fetches the Cypress application. I would use lockfile-driven package installation and cache the Cypress binary folder separately with an OS, architecture, and package-version-aware key. A dedicated verify step catches a bad restore early.

Frequently Asked Questions

Why does Cypress say failed to start during cypress verify?

The CLI found a binary to launch, but its smoke check could not complete. Read the next error line for a missing file, Linux library, display, permission, or timeout cause. Run DEBUG=cypress:cli* npx cypress verify to expose more launch detail.

How do I reinstall the Cypress binary without changing the npm package?

From the project root, run npx cypress install --force. It replaces the cached application for the installed package version. Confirm with npx cypress version and npx cypress verify.

Does npm ci install the Cypress desktop binary?

Normally Cypress downloads the binary during its postinstall step. If scripts are ignored, a download fails, or a cache is restored incorrectly, npm can finish while the application is unavailable. Run npx cypress install explicitly in that case.

What does Cypress verify check?

It checks that the cached Cypress application is installed and executable by launching a smoke test. It does not run your spec files or prove that your application server is reachable.

How do I find a missing Cypress dependency on Linux?

Run ldd on the cached Cypress executable and inspect lines ending in not found. Install the corresponding OS package from the Cypress prerequisites for your distribution. Then rerun npx cypress verify in the same container or VM.

Why does Cypress verify pass locally but fail in CI?

The CI runner has its own platform, cache, user, memory limit, and display setup. Install and verify inside that environment. Do not assume that node_modules or a binary copied from your laptop supplies a compatible application.

Should I use CYPRESS_SKIP_VERIFY to solve a startup error?

Usually no. It bypasses the smoke check and can hide a missing binary or OS dependency. Reserve it for a known executable in a deliberately read-only location after testing that it launches.

Related Guides