Selenium "WebDriverException: unknown error: Chrome failed to start: crashed" in CI

By Kaveh Alemi·Latchkey

Chrome's sandbox requires kernel privileges that an unprivileged CI container does not grant, so Chrome exits immediately and ChromeDriver reports "Chrome failed to start: crashed". Passing --no-sandbox lets headless Chrome run in the container.

What this error means

The driver fails at startup with "selenium.common.exceptions.WebDriverException: Message: unknown error: Chrome failed to start: crashed" and "(chrome not reachable)" on a Docker-based runner.

selenium

selenium.common.exceptions.WebDriverException: Message: unknown error: Chrome failed to start: crashed.
  (chrome not reachable)
  (The process started from chrome location /usr/bin/google-chrome is no longer running,
  so ChromeDriver is assuming that Chrome has crashed.)

Diagnose it: browser, server, or timing?

End-to-end failures in CI are dominated by three causes that have nothing to do with the test: the browser binary is missing, the application under test is not listening yet, or the test raced the page. Establish which before reading the assertion.

Terminal

# 1. are the browsers actually installed in THIS job?
npx playwright install --with-deps chromium
npx playwright --version

# 2. is the app up before the tests start?
npx wait-on http://localhost:3000 --timeout 60000

# 3. capture evidence for the failure you cannot reproduce
npx playwright test --trace on --video retain-on-failure

Common causes

The Chrome sandbox cannot initialize in the container

Running as root in a container without the SUID sandbox helper or the needed namespaces makes Chrome abort during sandbox setup.

Too little shared memory for the renderer

The default 64 MB /dev/shm in a container can starve the renderer, so Chrome crashes right after launch.

How to fix it

Add --no-sandbox and --disable-dev-shm-usage

Add --no-sandbox to the ChromeOptions so Chrome skips the sandbox helper.
Add --disable-dev-shm-usage so Chrome writes to /tmp instead of the small /dev/shm.
Re-run the suite headless in the container.

python

from selenium.webdriver.chrome.options import Options
opts = Options()
opts.add_argument("--headless=new")
opts.add_argument("--no-sandbox")
opts.add_argument("--disable-dev-shm-usage")

Or give the container more shared memory

When you control the container, mounting a larger /dev/shm avoids the renderer crash without disabling the sandbox.

.github/workflows/ci.yml

options:
  --shm-size=2g

Make the browser cache safe

Key the browser cache to the exact test-runner version. A cache restored from a different version gives you a binary that does not match the client and fails in a way that reads like a missing install.
Install browsers after dependencies, not before; a dependency install can replace the package that owns the browser path.
Prefer the vendor container image when the runner allows it. It removes the whole class of missing-system-library failures.

How to prevent it

Always pass --no-sandbox and --disable-dev-shm-usage for headless Chrome in containers.
Raise --shm-size when you control the container runtime.
Use a runner image known to run headless Chrome rather than a bare slim image.

Frequently asked questions

What causes Selenium "WebDriverException: unknown error: Chrome failed to start: crashed" in CI?

There are 2 common causes: the chrome sandbox cannot initialize in the container and too little shared memory for the renderer. Running as root in a container without the SUID sandbox helper or the needed namespaces makes Chrome abort during sandbox setup.

How do I fix Selenium "WebDriverException: unknown error: Chrome failed to start: crashed" in CI?

There are 2 fixes depending on which cause you have: add --no-sandbox and --disable-dev-shm-usage and or give the container more shared memory. Work through them in order, since the first is the most common.

What does Selenium "WebDriverException: unknown error: Chrome failed to start: crashed" in CI actually mean?