Karma "Cannot start Chrome / No binary" - Headless in CI

By Kaveh Alemi·Latchkey

Karma launches a real browser to run tests. In CI there is no display and often no sandbox, so a plain Chrome launcher fails to start - you need a headless, no-sandbox configuration and a valid CHROME_BIN.

What this error means

Karma fails to launch with "Cannot start Chrome," "No binary for Chrome browser on your platform," or a captured-browser timeout. The browser process either is not found or cannot start headless in CI.

Karma output

ERROR [launcher]: No binary for Chrome browser on your platform.
  Please, set "CHROME_BIN" env variable.
ERROR [launcher]: Cannot start Chrome
  Timed out waiting for the browser to be captured.

Diagnose it: is the test deterministic?

Before debugging an assertion, establish whether the test fails consistently. A test that passes alone and fails in the suite is sharing state; one that fails intermittently is racing something. Neither is fixed in the assertion.

Terminal

# in isolation
<runner> path/to/one.test

# order dependence
<runner> --shuffle   # or the runner equivalent

# raciness
for i in $(seq 1 20); do <runner> path/to/one.test || break; done

Common causes

No headless/no-sandbox launcher configured

The default Chrome launcher expects a display and a sandbox. In a container neither exists, so the browser cannot be captured.

CHROME_BIN not set or browser not installed

Karma cannot find the Chrome binary because it is not installed or CHROME_BIN does not point at it.

How to fix it

Use a custom ChromeHeadless launcher

karma.conf.js

// karma.conf.js
browsers: ['ChromeHeadlessCI'],
customLaunchers: {
  ChromeHeadlessCI: {
    base: 'ChromeHeadless',
    flags: ['--no-sandbox', '--disable-gpu', '--disable-dev-shm-usage'],
  },
},

Install Chrome and set CHROME_BIN

Terminal

export CHROME_BIN=$(which google-chrome || which chromium)
# or in the workflow, install a known browser before testing

How to prevent it

Use a ChromeHeadless custom launcher with --no-sandbox in CI.
Install a known browser and set CHROME_BIN explicitly.
Add --disable-dev-shm-usage to avoid small /dev/shm crashes.

Frequently asked questions

What causes Karma "Cannot start Chrome / no binary"?

There are 2 common causes: no headless/no-sandbox launcher configured and chrome_bin not set or browser not installed. The default Chrome launcher expects a display and a sandbox.

How do I fix Karma "Cannot start Chrome / no binary"?

There are 2 fixes depending on which cause you have: use a custom chromeheadless launcher and install chrome and set chrome_bin. Work through them in order, since the first is the most common.

What does Karma "Cannot start Chrome / no binary" actually mean?

Karma fails to launch with "Cannot start Chrome," "No binary for Chrome browser on your platform," or a captured-browser timeout.

How do I stop Karma "Cannot start Chrome / no binary" happening again?

Use a ChromeHeadless custom launcher with --no-sandbox in CI. The prevention section lists 3 changes that keep it from recurring.

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.

References

GitHub Actions documentation