Selenium — WebDriverException: unknown error on browser start

Fix Selenium WebDriverException by matching the driver to the browser version and running headless with adequate container resources.

intermediatedebuggingpythonselenium

Symptoms

WebDriverException: unknown error: Chrome failed to start
The browser crashes on launch in Docker or CI
The driver and browser versions are incompatible
The error mentions DevToolsActivePort or a non-existent file

Possible causes

The browser and driver versions do not match
The container lacks shared memory or the required sandbox flags
No display is available so the browser cannot start in headful mode
A previous browser process is still running and holds a lock

Diagnosis steps

Check browser and driver versions

google-chrome --version && chromedriver --version

Interpretation

Mismatched major versions cause startup failures. Selenium Manager can fetch a matching driver automatically.

Run headless with sandbox flags in Docker

python -c "from selenium import webdriver; o=webdriver.ChromeOptions(); o.add_argument('--headless=new'); o.add_argument('--no-sandbox'); print(webdriver.Chrome(options=o))"

Interpretation

A successful headless start with no-sandbox confirms the container environment, not the app, is the issue.

Increase shared memory in the container

docker run --shm-size=1g image

Interpretation

Chrome needs substantial shared memory; the default 64MB in some runtimes causes crashes that look like driver errors.

Root cause

The browser failed to launch because the driver did not match the browser, the container lacked a display or shared memory, or sandboxing blocked startup, not because of the test code.

Fix

Match the driver to the browser version, run headless with the appropriate flags, and give the container enough shared memory. Reuse a single driver per session and quit it cleanly.

Verify the fix

Launch the browser and confirm a page loads, then run the test suite and confirm it passes without WebDriverException.

Symptom walkthrough

Starting a Selenium session raises WebDriverException with a message such as unknown error: Chrome failed to start or DevToolsActivePort file does not exist. It is most common in containers and CI, where the browser has no display, insufficient shared memory, or a version that does not match the installed driver.

Fix in practice

Align the browser and driver versions, ideally letting Selenium Manager fetch the matching driver, and run headless with the no-sandbox and disable-dev-shm-usage flags where appropriate. Increase the container shared memory so the browser process can start reliably.

Verification

Launch the browser and confirm a page loads, then run the test suite and confirm it completes without the exception. A stable run under the same container settings is the real proof. Recording the container image and flags alongside the test keeps future failures reproducible.

Diagnostic commands

Check the behavior with commands like these:

google-chrome --version && chromedriver --version
python -c "from selenium import webdriver; o=webdriver.ChromeOptions(); o.add_argument('--headless=new'); o.add_argument('--no-sandbox'); print(webdriver.Chrome(options=o))"
docker run --shm-size=1g image