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

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.

Karma output

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

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

// 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

Install Chrome/Chromium in the runner image, or use puppeteer to provide one.
Export CHROME_BIN to the installed binary path.
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.