TestCafe "Unable to establish ... browser connection" in CI

TestCafe starts a browser and waits for it to connect back to the TestCafe proxy. If the browser launches headed when no display exists, or is too slow to connect, TestCafe aborts with "Unable to establish one or more of the specified browser connections".

What this error means

TestCafe fails before tests run with "Error: Unable to establish one or more of the specified browser connections. This can be caused by network issues or remote device failure."

Error: Unable to establish one or more of the specified browser connections.
This can be caused by network issues or remote device failure.
1 of 1 browser connections have not been established:
- chrome

Common causes

A headed browser on a runner with no display

Without :headless, the browser tries to open a window on a CI runner that has no X server, so it never connects.

The browser was too slow to connect

A contended runner or a sandbox crash delayed the browser past the connection timeout, so TestCafe gave up.

How to fix it

Run the browser headless

1. Append :headless to the browser alias so no display is needed.
2. Pass container-safe flags via the browser command for Chromium.
3. Re-run so the browser connects back to TestCafe.

npx testcafe "chrome:headless --no-sandbox --disable-dev-shm-usage" tests/

Or provide a virtual display

If you must run headed, wrap the run in xvfb so a display exists for the browser window.

xvfb-run --auto-servernum npx testcafe chrome tests/

How to prevent it

• Use the :headless alias for browsers in CI.
• Pass --no-sandbox and --disable-dev-shm-usage to Chromium in containers.
• Use xvfb only when a headed browser is genuinely required.

Related guides