The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
When ChromeDriver fails in Selenium headless mode, start by checking the Chrome and ChromeDriver major versions, then confirm Selenium is using the intended browser binary and headless argument. In current Chrome, use --headless=new. If those are correct, inspect the startup log, profile directory, executable permissions, and CI or container environment rather than adding flags at random.
What to check first when a headless session will not start
Headless mode changes how Chrome runs; it does not remove Selenium’s need to start a compatible browser process. A “Chrome failed to start” or “DevToolsActivePort file doesn’t exist” message can result from a driver mismatch, an incorrect browser path, a profile that cannot be used, or an environment that prevents Chrome from launching. Treat the message as a clue to startup failure, not as proof of one specific cause.
- Record the versions and paths. Find the installed Chrome version, ChromeDriver version, Selenium binding version, and actual Chrome executable path. Chrome and ChromeDriver must match at the major-version level, according to Selenium’s Chrome documentation.
- Check how Selenium obtains ChromeDriver. If you supply a driver manually, confirm it is the one being used and that its directory is on
PATHor its path is configured explicitly. If no driver is supplied, use Selenium Manager where available. - Use a headless argument supported by your Chrome version. For current Chrome, configure
--headless=new. The historical--headless=chromeargument applied to Chrome 96–108; Selenium’s transition guidance says--headless=newapplies after version 109. - Check the browser binary and profile. Set the binary location if Chrome is installed outside its normal location. Give concurrent sessions separate, writable user-data directories.
- Read the complete startup log. If Chrome exits immediately, enable ChromeDriver logging and inspect the browser and driver paths, profile permissions, executable permissions, and the CI or container runtime.
Change one thing at a time. Once a minimal session works, add your application’s selectors, waits, custom browser settings, and parallelism incrementally; that makes the change that reintroduces the failure easier to identify.
Make ChromeDriver match Chrome
Selenium’s Chrome documentation states that the Chrome browser and ChromeDriver versions must match at the major-version level. A mismatch can prevent session creation even when the driver executable exists and can be launched. Comparing only whether both programs are installed is not enough: record their full version strings and compare the leading major version.
#1 Best Overall
Let Selenium Manager resolve the driver when possible
Selenium Manager is included with Selenium 4.6 and later. When you have not supplied a driver, it can detect the installed browser, resolve the corresponding driver using vendor metadata, download it, and cache it. This is usually the simplest route for a local developer machine or a CI job with the required network access.
If an old manually downloaded driver is being selected, remove it from the configuration or PATH when you intend Selenium Manager to take over. Otherwise, you may continue to launch the stale executable without realizing it. Selenium Manager is a fallback when no driver is provided; it does not override a driver path you explicitly configure.
Use an explicit driver path when you need manual control
Manual driver management can be appropriate when your environment pins browser and driver versions, restricts downloads, or provides a preinstalled driver. In that case, verify the executable path and version as part of the environment setup. If the executable is not found, either add its directory to PATH or provide its location with Selenium’s service API. Do not treat a PATH fix as a version fix: both the executable location and major-version compatibility matter.
Choose the right headless argument
Set the headless argument through ChromeOptions. For current Chrome, use --headless=new. Selenium’s headless transition guidance distinguishes the older --headless=chrome spelling, used for Chrome versions 96 through 108, from --headless=new, used after version 109. If an older browser is pinned, select the argument for that browser version instead of assuming a flag that works on a newer local machine will work in CI.
Headless versus headed operation is also a useful diagnostic comparison. If the same browser and driver start when headless mode is removed but fail when it is enabled, you have narrowed the difference to the headless configuration or environment; it does not by itself establish whether the root cause is Chrome, the runtime, or an application-specific setting. Keep the rest of the configuration constant while comparing.
Use this minimal Python test
This small script tests whether Selenium can launch Chrome, load a page, and close the session cleanly. Install the Selenium Python binding in the environment where you run it, and ensure that Chrome is installed there too.
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
options.add_argument("--headless=new")
# Set this only if Chrome is installed outside its default location:
# options.binary_location = "/path/to/chrome"
# Use a different writable path for each concurrent session:
# options.add_argument("--user-data-dir=/tmp/selenium-profile-unique")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()Run the script from the same machine, container, virtual environment, and account that exhibit the failure. If it works, add your real navigation and options gradually. If it fails, use the next sections to isolate the startup problem.
Set Chrome’s binary and give parallel sessions separate profiles
ChromeOptions controls headless mode, browser binary selection, and profile configuration. If Chrome is not in the default location for that operating system or runtime, set options.binary_location to the actual browser executable. Confirm the path exists in the environment where the test runs; a path from the host machine may not exist inside a container.
Chrome uses a user-data directory for profile state. Reusing the same profile across overlapping sessions can cause a conflict, and an unwritable profile directory can prevent startup. When sessions run in parallel or repeatedly under automation, assign each session its own writable --user-data-dir. Make sure the process account can create and write to it. Avoid deleting a profile while Chrome is still using it.
Diagnose CI and container startup failures
When the version, headless argument, binary path, and profile are correct but Chrome still exits immediately, investigate the runtime rather than layering on generic flags.
- Permissions: Verify the account running the job can execute both Chrome and ChromeDriver and can write to the profile and temporary directories.
- Runtime dependencies: Check that the container or CI image includes the libraries required by Chrome. A browser that works on a developer workstation may not launch in a more minimal image.
- Environment boundaries: Confirm that the browser path, driver path, writable directories, and network access expected by the job are available inside the job’s actual container or runner.
- Startup evidence: Enable ChromeDriver logging and inspect the full startup message, including lines before the final exception. Selenium’s installation guidance recommends logging and, when a current installation still fails, filing a bug report.
Do not add environment-specific flags merely because they appear in an unrelated example. The useful flag depends on the runtime and the error evidence. Add a flag only when it addresses a condition you have identified, then rerun the minimal test.
Recommended Free Tools
Common errors and the next action
| Symptom | Likely area to inspect | Next action |
|---|---|---|
| Session creation fails and Chrome/ChromeDriver major versions differ | Driver selection or a manually pinned binary | Use a matching driver, or remove the stale manual driver and allow Selenium Manager to resolve one if the environment permits. |
| ChromeDriver or the browser executable cannot be found | PATH, service configuration, or browser installation path | Put the executable directory on PATH or configure the explicit driver path; set Chrome’s binary location if its installation is nonstandard. |
| “DevToolsActivePort file doesn’t exist” or Chrome exits at startup | Startup failure, not a unique diagnosis | Check the preceding log, then verify version compatibility, binary location, profile writability, permissions, and runtime dependencies. |
| Failure occurs only in parallel or repeated runs | Shared or unwritable Chrome profile | Give each session a unique writable user-data directory and avoid reusing an active profile. |
| Local run works but CI/container run fails | Different paths, account permissions, dependencies, or network access | Run the minimal script in the job’s actual environment and compare its paths and logs with the working environment. |
| Failure starts after changing only the headless option | Headless argument versus Chrome version | Use the argument appropriate to the pinned Chrome version; current Chrome uses --headless=new. |
Performance, reliability, and maintenance
For reliability, keep the browser and driver versions controlled as a pair, and make the environment that starts Chrome explicit: binary path, profile path, executable permissions, and runtime dependencies. Selenium Manager reduces the maintenance of manually finding and downloading a compatible driver, but its initial resolution requires the environment to be able to access the necessary vendor metadata and download. Environments without that access need a driver provisioned through their own controlled process.
Rank #4
For parallel runs, separate profiles rather than having sessions compete for one user-data directory. For troubleshooting, keep a minimal startup test and logs available in CI; this distinguishes a browser-launch problem from a later page-load or test assertion failure. There is no single additional headless flag that makes every environment reliable, and the failure-rate figures are not established in the cited Selenium guidance.
Or skip the browser setup
If your goal is to obtain a website screenshot rather than operate Selenium, ScreenshotNeo is a website screenshot API and MCP server made by Yorker Media. One GET request can return a PNG, JPEG, WebP, or PDF. Here is a Python call using the documented API; see the ScreenshotNeo API documentation for options.
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot; each of those steps can be turned off. Bot checks, blank pages, and failed loads are never billed, and response headers report the page verdict and billing status. An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Sign up for 1,000 free screenshots a month, with no card required.
Frequently asked questions
What does “DevToolsActivePort file doesn’t exist” tell me?
It indicates Chrome did not complete startup in the way ChromeDriver expected. The message alone does not identify the cause; use the startup log and check the browser, driver, profile, permissions, and runtime.
Frequently Asked Questions
What does “DevToolsActivePort file doesn’t exist” tell me?
It indicates Chrome did not complete startup in the way ChromeDriver expected. The message alone does not identify the cause; use the startup log and check the browser, driver, profile, permissions, and runtime.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
