Cypress "Failed to start Cypress" / Xvfb error in CI

Cypress runs the browser through Xvfb (an in-memory X server) on Linux. If Xvfb is not installed, or cannot start, Cypress cannot open a display and fails before any test. The official Cypress Docker images include Xvfb already.

What this error means

Cypress aborts with "Your system is missing the dependency: Xvfb" or "Failed to start Cypress: ... Could not connect to the X server" on a minimal Linux container.

cypress

Your system is missing the dependency: Xvfb

Install Xvfb and run Cypress again.

Read our documentation on dependencies for more information:
https://on.cypress.io/required-dependencies

Common causes

Xvfb is not installed on the runner

Headless Linux images do not ship Xvfb by default, so Cypress has no virtual display to launch the browser into.

Xvfb installed but missing X11 libraries

Xvfb starts but the browser cannot connect because supporting X11/GTK libraries are absent on a slim image.

How to fix it

Use the official Cypress Docker image

The cypress/included image bundles Xvfb, browsers, and every system library, so nothing is missing.

.github/workflows/ci.yml

container:
  image: cypress/included:13.15.0

Install Xvfb and dependencies on a bare image

When you manage the image yourself, install Xvfb and the documented Cypress Linux dependencies.

Dockerfile

apt-get update && apt-get install -y \
  xvfb libgtk-3-0 libgbm-dev libnss3 libasound2

How to prevent it

Prefer the cypress/included or cypress/browsers images in CI.
Install the full Cypress Linux dependency list on custom images.
Run a cypress verify smoke step to catch a broken display early.