Sporadic "Missing X server or $DISPLAY"

[MikeMcC399]

Current behavior

Cypress verification in CircleCI jobs sporadically fails with a "Missing X server or $DISPLAY" error. Re-running the job generally recovers from the error.

Desired behavior

Cypress verification in CircleCI jobs should not fail with a "Missing X server or $DISPLAY" error.

Test code to reproduce

This is a sporadic issue, not a hard error that always occurs. It has been observed running .circleci/test-deploy.yml in this repo.

Cypress Version

14.3.2

Node version

v22.15.0 LTS and
v22.17.0 LTS

Operating System

Ubuntu 22.04.3 LTS
docker.io/cimg/node:22.15.0-browsers
and
Ubuntu 24.04.2 LTS
docker.io/cimg/node:22.17.0-browsers

Logs

An example log is https://app.circleci.com/pipelines/github/cypress-io/circleci-orb/2089/workflows/81e47d76-d64e-4b26-a54e-7d96ffd38626/jobs/9077

Cypress failed to start.

This may be due to a missing library or dependency. https://on.cypress.io/required-dependencies

Please refer to the error below for more details.

----------

[220:0616/212755.163287:ERROR:bus.cc(407)] Failed to connect to the bus: Failed to connect to socket /run/dbus/system_bus_socket: No such file or directory
[220:0616/212755.757734:ERROR:ozone_platform_x11.cc(245)] Missing X server or $DISPLAY
[220:0616/212755.757747:ERROR:env.cc(258)] The platform failed to initialize.  Exiting.

----------

Platform: linux-x64 (Ubuntu - 22.04)
Cypress Version: 14.3.2

Exited with code exit status 1

Other

This issue has also been previously reported in

• Missing X server or $DISPLAY cypress#31484
• https://discuss.circleci.com/t/xvfb-frequently-fails-to-start-with-browsers-convenience-image/53164

cc: @JeremieDoctrine

[MikeMcC399]

Background

Executor cypress/default uses cimg/node:<< parameters.node-version >>-browsers

cimg/node:22.15.0-browsers is based on

cimg/node:22.15.0 is based on

cimg/base:2024.02 released on Feb 29, 2024 and is based on

Ubuntu 22.04.3 LTS which was released on August 10, 2023

The entrypoint of cimg/node:22.15.0-browsers is /docker-entrypoint.sh with the following contents:

/docker-entrypoint.sh

#!/bin/sh
Xvfb :99 -screen 0 1280x1024x24 &
exec "$@"

[MikeMcC399]

• I have requested the CircleCI update their convenience images cimg/node to a current version of Ubuntu. See Maintenance Request: Update to current cimg:base according to policy CircleCI-Public/cimg-node#462

• Running apt update in the Docker image cimg/node:22.15.0-browsers shows 139 pending updates. Although this does not include any update to Xvfb, there may be some interactions with other updates, and updating may possibly help.

This is the version used in Ubuntu 22.04.3 and .5

$ apt list xvfb
Listing... Done
xvfb/now 2:21.1.4-2ubuntu1.7~22.04.14 amd64 [installed,local]

[MikeMcC399]

Workaround

Use a Cypress Docker image instead of the default executor from the Cypress Orb, for example:

executor:
  docker:
    image: cypress/browsers:22.15.0 # your Docker image here

[MikeMcC399]

Another (possible) workaround

It's not clear from the logs, whether Xvfb in the cimg/node-<version>-browsers Docker image is completely failing to start or whether it is just slow. It fails anyway in Cypress' verify step.

If it's just a case of it being slow, it may be possible to simply skip Cypress verification using CYPRESS_SKIP_VERIFY=true as a Cypress environment variable.

Edit: This probably won't work. According to the comment in https://discuss.circleci.com/t/xvfb-frequently-fails-to-start-with-browsers-convenience-image/53164

I’ve written a script to detect when the display is booted up by checking the /tmp/.X11-unix directory. But after waiting for 2 minutes, on the builds that fail, Xvfb has still not loaded.

[MikeMcC399]

CircleCI has apparently stopped, or at least paused, updating all their images 🙁

According to https://circleci.com/docs/convenience-images-support-policy/ you would expect to see new images with a regular cadence of 3 months.

If there is no response to CircleCI-Public/cimg-node#462 within the next week or two, this would probably need to be escalated.

[MikeMcC399]

• PR Update cimg/base version to 2025.06 CircleCI-Public/cimg-node#463 submitted to propose that the image get updated

[MikeMcC399]

The https://github.com/CircleCI-Public/cimg-node repo has been updated to generate new cimg/node images based on Ubuntu 24.04.2 LTS. Possibly by the end of this week, with new Node.js releases coming out, there will be new cimg/node images available on this basis. This would allow testing to see if the X server issue still occurs.

[MikeMcC399]

Unfortunately, the hope has been dashed that the issue of "Missing X server or $DISPLAY" would be mitigated by getting the CircleCI Docker images cimg/node:<node-version>-browsers updated to be built based on Ubuntu 24.04.2 LTS.

When PR #541 was merged into the master branch, the job Run CT Tests in Edge failed with "Missing X server or $DISPLAY" although all other jobs succeeded.

So, this continues to be a flaky situation where using identical executors, now based on Ubuntu 24.04, sometimes Cypress fails to run in varying jobs. The full example error was:

[698:0626/142520.043844:ERROR:ozone_platform_x11.cc(245)] Missing X server or $DISPLAY
[698:0626/142520.043859:ERROR:env.cc(258)] The platform failed to initialize.  Exiting.
The Test Runner unexpectedly exited via a exit event with signal SIGSEGV

Please search Cypress documentation for possible solutions:

https://on.cypress.io

Check if there is a GitHub issue describing this crash:

https://github.com/cypress-io/cypress/issues

Consider opening a new issue.

----------

Platform: linux-x64 (Ubuntu - 24.04)
Cypress Version: 14.3.2

Exited with code exit status 1

More investigation is necessary.