TestCafe "Unable to find the browser" - Headless Browser Launch in CI

By Kaveh Alemi·Latchkey

TestCafe resolves a browser alias (e.g. chrome) to an installed binary and launches it. In CI the alias has no matching browser, the run is not headless, or the container needs sandbox flags - so the launch fails before tests run.

What this error means

TestCafe exits with "Unable to find the browser. The specified browser is not found." or the browser never connects. The same command works locally where a real browser is installed and a display exists.

ERROR Unable to find the browser. "chrome" is not found.

Browser aliases:
  "chrome", "chrome:headless", "firefox" ... (none installed on runner)

Common causes

No installed binary for the alias

The runner has no Chrome/Firefox matching the chrome/firefox alias, so TestCafe cannot resolve and launch it.

Not headless / missing container flags

Without :headless, TestCafe tries to open a window on a display-less runner; and in a container, Chrome needs --no-sandbox to start.

How to fix it

Run a headless browser with sandbox flags

Use the :headless alias and pass container-safe flags after --.

npx testcafe "chrome:headless --no-sandbox --disable-gpu" tests/

Install or provide the browser in CI

1. Install Chrome/Chromium in the runner image, or use a TestCafe browser-provider plugin.
2. Confirm the alias resolves with testcafe --list-browsers.
3. Add --disable-dev-shm-usage when the container’s shared memory is small.

How to prevent it

• Install a headless browser in the CI image.
• Always use the :headless alias in CI with sandbox flags.
• Verify available browsers with --list-browsers before the run.

Frequently asked questions

Related guides

References

• GitHub Actions documentation