Cypress "Timed out waiting for the browser to connect" verify in CI

On first run Cypress verifies its binary by briefly opening the browser. If that open hangs (no Xvfb, missing libraries, or a slow cold container), the verification times out and Cypress refuses to run tests. The failure is almost always an environment problem, not the binary itself.

What this error means

Cypress fails with "Timed out waiting for the browser to connect. Retrying..." then "Cypress verification timed out" before any spec executes.

cypress

Verifying Cypress can run /root/.cache/Cypress/13.15.0/Cypress
Timed out waiting for the browser to connect. Retrying...
✖  Cypress verification timed out.

This command failed with the following output:
.../Cypress: error while loading shared libraries: ...

Common causes

Missing Xvfb or system libraries

Without a display or a linked library, the verification browser never connects, so the smoke check times out.

A slow or resource-starved container

On an under-provisioned runner the cold browser start can exceed the verification timeout even when nothing is missing.

How to fix it

Fix the environment, then verify explicitly

Install Xvfb and the documented Cypress dependencies (or use a Cypress image).
Run cypress verify as its own step to surface the real error.
Re-run the suite once verification passes.

Terminal

npx cypress verify

Raise the verify timeout for slow runners

Increase the verification timeout so a slow cold start is not mistaken for a broken binary.

.github/workflows/ci.yml

env:
  CYPRESS_VERIFY_TIMEOUT: '100000'

How to prevent it

Verify Cypress in a dedicated step so failures are explained, not hidden.
Use an image with Xvfb and dependencies already present.
Allow extra verify timeout on small CI runners.