Heuristic:Cypress io Cypress Xvfb Display Gotcha
| Knowledge Sources | |
|---|---|
| Domains | Debugging, Linux, CI |
| Last Updated | 2026-02-12 01:00 GMT |
Overview
On Linux, if the DISPLAY environment variable is set but points to a non-working X11 server, Cypress will exit silently without explanation. Unset DISPLAY to let Cypress manage its own Xvfb.
Description
Cypress checks for the `DISPLAY` environment variable on Linux to decide whether to spawn its own Xvfb virtual framebuffer. If DISPLAY is set, Cypress assumes a working X11 server exists and does not start Xvfb. If that X11 server is broken or non-existent, Cypress (specifically Electron) will crash silently with no useful error message. This is a well-known gotcha documented in GitHub issue #4034.
Additionally, the Xvfb screen resolution must be explicitly defined as `1280x1024x24` — without this explicit screen argument, Electron will crash (GitHub issue #6184).
Usage
Apply this heuristic when debugging silent Cypress crashes on Linux, configuring CI pipelines, or troubleshooting Docker-based test execution. If Cypress exits without any error output on Linux, the DISPLAY variable is the first thing to check.
The Insight (Rule of Thumb)
- Action: Unset the DISPLAY variable when running Cypress in CI or headless environments: `DISPLAY= npx cypress run`
- Value: Let Cypress auto-manage Xvfb with its hardcoded screen resolution of `1280x1024x24`
- Trade-off: You lose the ability to use an existing X11 server; Cypress spawns its own Xvfb with a 30-second timeout
Reasoning
The DISPLAY variable is a standard Unix convention for X11 server location. Many CI environments, Docker containers, or SSH sessions may have stale DISPLAY values from previous sessions. Cypress cannot reliably validate whether the DISPLAY points to a working server before launching Electron, so it trusts the variable. The explicit screen argument (`-screen 0 1280x1024x24`) was added after Electron crash reports on default Xvfb configurations.
Code Evidence
Silent exit path from `cli/lib/exec/xvfb.ts:83-100`:
if (process.env.DISPLAY) {
const issueUrl = util.getGitHubIssueUrl(4034)
const message = stripIndent`
DISPLAY environment variable is set to ${process.env.DISPLAY} on Linux
Assuming this DISPLAY points at working X11 server,
Cypress will not spawn own Xvfb
NOTE: if the X11 server is NOT working, Cypress will exit without explanation,
see ${issueUrl}
Solution: Unset the DISPLAY variable and try again:
DISPLAY= npx cypress run ...
`
debug(message)
return false
}
Mandatory screen resolution from `cli/lib/exec/xvfb.ts:17-19`:
// need to explicitly define screen otherwise electron will crash
// https://github.com/cypress-io/cypress/issues/6184
xvfb_args: ['-screen', '0', '1280x1024x24'],