Karma "No binary for ChromeHeadless" - Headless Browser in CI

By Kaveh Alemi·Latchkey

Karma could not find a Chrome binary to launch in headless mode. On a CI runner Chrome may not be installed, CHROME_BIN is not pointed at it, or Chrome refuses to start without --no-sandbox inside a container.

What this error means

Karma aborts at startup with "No binary for ChromeHeadless browser on your platform" or the browser never connects and the run times out. Locally it works because a real Chrome is installed and on PATH.

ERROR [launcher]: No binary for ChromeHeadless browser on your platform.
  Please, set "CHROME_BIN" env variable.

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.

# 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

Chrome not installed or CHROME_BIN unset

The runner has no Chrome/Chromium, or Karma cannot locate it because CHROME_BIN is not set to the binary path.

Chrome will not start without --no-sandbox

Inside a container running as root, Chrome’s sandbox blocks launch. Without a custom launcher adding --no-sandbox/--headless=new, the browser never connects.

How to fix it

Install Chrome and define a CI launcher

Set CHROME_BIN and add a custom launcher with the container-safe flags.

// karma.conf.js
process.env.CHROME_BIN = require('puppeteer').executablePath();
module.exports = (config) => config.set({
  browsers: ['ChromeHeadlessCI'],
  customLaunchers: {
    ChromeHeadlessCI: { base: 'ChromeHeadless', flags: ['--no-sandbox', '--headless=new'] },
  },
});

Wire the binary into CI

1. Install Chrome/Chromium in the runner image, or use puppeteer to provide one.
2. Export CHROME_BIN to the installed binary path.
3. Run with --single-run so CI exits after one pass.

How to prevent it

• Install a headless Chrome in the CI image and set CHROME_BIN.
• Use a custom launcher with --no-sandbox in containers.
• Run Karma with --single-run in CI.

Frequently asked questions

Related guides

References

• GitHub Actions documentation