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.

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.

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
browsers: ['ChromeHeadlessCI'],
customLaunchers: {
  ChromeHeadlessCI: {
    base: 'ChromeHeadless',
    flags: ['--no-sandbox', '--disable-gpu', '--disable-dev-shm-usage'],
  },
},

Install Chrome and set CHROME_BIN

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

Related guides

References

• GitHub Actions documentation