Diagnosing Karma Chrome Launcher Startup Failures

Recognizable condition

When you run karma start the output contains lines such as:

ERROR [launcher]: Cannot start Chrome
Failed to launch Chrome

No browser window appears and the test suite never proceeds to execution.

Short cause / diagnostic table

Possible cause	What to look for
Chrome binary not found or wrong path	CHROME_BIN unset, empty, or pointing to a non‑existent file
Missing or mis‑specified browsers array in Karma config	Config lacks browsers: ['Chrome'] or uses a typo
Out‑of‑date karma‑chrome‑launcher version	Launcher version incompatible with installed Chrome major version
System‑level restrictions (SELinux, AppArmor, corporate proxy)	Launcher process is killed or denied exec permission

Ordered checks

1. Verify Chrome installation

   Run the command where you usually develop (local workstation or CI agent).

   # Linux/macOS
   which google-chrome || which chromium-browser || which chromium
   # Windows (PowerShell)
   Get-Command chrome.exe -ErrorAction SilentlyContinue
   

   Expected output: an absolute path to the executable. If nothing is returned, Chrome is not installed or not on PATH.

   Risk: None – this is a read‑only check.

2. Check the CHROME_BIN environment variable

   In the same shell where you launch Karma:

   echo $CHROME_BIN   # Linux/macOS
   echo %CHROME_BIN%  # Windows CMD
   

   If the variable is set, confirm the path exists and is executable:

   test -x "$CHROME_BIN" && echo "OK" || echo "Missing or not executable"
   

   If unset or incorrect, you will need to set it (see fixes).

3. Inspect Karma configuration

   Open karma.conf.js and locate the browsers property.

   module.exports = function(config) {
     config.set({
       browsers: ['Chrome'],   // <-- must be present and correctly spelled
       // … other options
     });
   };

   If the array is missing, empty, or contains a typo (e.g., 'Chrone'), the launcher will not be invoked.

4. Check launcher version compatibility

   List the installed launcher version and compare it with Chrome’s major version.

   # See launcher version
   npm list karma-chrome-launcher
   # See Chrome major version
   google-chrome --version  # or chromium-browser --version
   

   As of Karma Chrome Launcher v3.x, it supports Chrome 109+. If your Chrome is older, upgrade Chrome or downgrade the launcher to a compatible release (e.g., v2.x for Chrome < 109).

5. Look for system security policies

   On Linux with SELinux or AppArmor, check audit logs for denials when Karma runs.

   # SELinux
   ausearch -m avc -ts recent
   # AppArmor
   sudo aa-logprof
   

   If you see messages like "operation=exec" denied for the Chrome binary, the policy is blocking execution.

Fixes tied to findings

Chrome binary not found

• Install Chrome (or Chromium) for your platform.
• If you prefer a custom location, export CHROME_BIN before launching Karma:

# Example for a custom Chromium build
 export CHROME_BIN=/opt/chromium-custom/chrome
 karma start

In CI pipelines, set the variable in the job definition (e.g., env: block in GitHub Actions).

Missing or wrong browsers array

Edit karma.conf.js to include:

browsers: ['Chrome'],

Save the file and rerun Karma.
Launcher version mismatch
Update to a compatible launcher:
npm install --save-dev karma-chrome-launcher@latest
# or pin a known‑good version
npm install --save-dev karma-chrome-launcher@^3.0.0

After installation, repeat npm list karma-chrome-launcher to confirm the version.
System‑level restrictions
If SELinux is enforcing, you can either:

Create a local policy module to allow the launcher to exec Chrome (advanced).
Temporarily set SELinux to permissive for testing: sudo setenforce 0 (remember to revert).

For AppArmor, adjust the profile for /usr/bin/google-chrome or use aa-complain to put the profile in complain mode.
In many corporate environments, a proxy or security suite may block the launcher’s attempt to spawn a process. Consult your IT team to whitelist the Chrome binary or disable the interfering component for the build agent.
Escalation criteria
Escalate to a senior engineer or platform team when:

Chrome is installed, CHROME_BIN points to a valid executable, the Karma config is correct, and the launcher version is compatible, yet the error persists.
Audit logs show a denial that cannot be resolved by adjusting local SELinux/AppArmor policies without violating security baselines.
The failure occurs only in a specific CI environment and reproduces nowhere else, suggesting infrastructure‑level constraints (e.g., container runtime restrictions, missing /dev/shm, or insufficient privileges).

When escalating, provide:

The full Karma log (including the launcher error).
Output of the checks above (which chrome, echo $CHROME_BIN, launcher version, Chrome version).
Relevant snippets from SELinux/AppArmor audit or proxy logs.

Verification after a fix
Run Karma again and look for the successful start message:
INFO [launcher]: Starting browser Chrome
INFO [Chrome ...]: Connected on socket ...

Confirm that a Chrome process appears with the expected arguments:
ps aux | grep chrome
# Example output:
# user 12345  0.2  1.5  1234567 89012 ? Sl   10:00   0:00 /usr/bin/google-chrome --headless --disable-gpu --remote-debugging-port=9876 http://localhost:9876/

If using CI, inspect the job artifact or log for the same “Starting browser Chrome” line and ensure the test execution summary follows without launcher‑related errors.
Limitations and practical checks
These steps assume you have permission to modify environment variables, install packages, and edit karma.conf.js. In locked‑down environments you may need to involve DevOps or security teams to adjust policies or provide a pre‑approved Chrome binary.
A practical way to confirm that the CHROME_BIN variable is being picked up by Karma is to add a temporary debug line to the config:
console.log('Using Chrome binary:', process.env.CHROME_BIN || '(unset)');

Remove the line after troubleshooting to avoid leaking paths in production logs.