Cypress binary "verification timed out" / failed to start in CI

After download, Cypress runs the binary once to verify it works. When that smoke test cannot open the browser (missing system libraries, no Xvfb, or a slow runner), it fails with "Cypress verification timed out" or "Cypress failed to start".

What this error means

The verify step (or the first cypress run) fails with "Cypress verification timed out. This command failed with the following output" or "Cypress failed to start" plus a list of missing libraries.

Cypress

Verifying Cypress can run /root/.cache/Cypress/13.9.0/Cypress
Cypress verification timed out.
This command failed with the following output:
  error while loading shared libraries: libgtk-3.so.0

Common causes

Missing GTK/GBM system libraries

The verification launches the Electron-based app, which links against GTK and other libraries the slim image does not have.

No virtual display for a headed run

A headed verification needs a display; without Xvfb the app cannot open a window and the smoke test times out.

How to fix it

Install Cypress OS dependencies

Add the libraries the Cypress docs list for Linux before verifying.

Terminal

sudo apt-get update
sudo apt-get install -y libgtk-3-0 libgbm1 libnss3 libasound2 \
  libxss1 libxtst6 xauth xvfb

Use the official Cypress image

The cypress/included image ships the dependencies and Xvfb, so verification passes.

.github/workflows/ci.yml

container:
  image: cypress/included:13.9.0

How to prevent it

Install the Cypress Linux dependencies (including Xvfb) on custom images.
Prefer a cypress/browsers or cypress/included image in CI.
Cache the Cypress folder so verification runs against a stable binary.