Fix Chrome Headless Crashing with “DevToolsActivePort file doesn’t exist”
Learn what the DevToolsActivePort error means and diagnose Chrome startup failures in headless runs, CI, containers, and profile-based setups.
If ChromeDriver reports DevToolsActivePort file doesn't exist, Chrome did not complete the startup handoff ChromeDriver expected. ChromeDriver checks for a DevToolsActivePort file in Chrome’s user-data directory; its absence identifies the failed check, but not the underlying cause. Start with ChromeDriver’s verbose log and Chrome’s startup output, then isolate the launch context one variable at a time. Chromium’s launcher implementation shows this check.
1. What the error means
ChromeDriver starts Chrome with a user-data directory and expects Chrome to create a file named DevToolsActivePort there as part of the remote debugging startup handoff. If the file is missing when ChromeDriver checks, it reports this error.
The message does not prove that a particular flag is missing, that versions are incompatible, or that Chrome itself is defective. Chrome may have exited before creating the file, may have been unable to use the selected profile or directory, or may have been prevented from enabling remote debugging. The first preceding browser or driver error is usually a more useful lead than the final missing-file message.
2. Collect the startup evidence first
- Record the operating system, Chrome or Chromium version, ChromeDriver version, Selenium version, browser executable path, driver path, and exact launch arguments.
- Enable ChromeDriver’s verbose logging and preserve Chrome’s stderr or process output. Find the first startup error before the missing-file report.
- Confirm the paths and versions belong to the actual processes launched by the job, not just the versions installed on the machine.
- Note whether the browser is managed by an organization, whether a custom profile is supplied, whether the run is headless, and whether it runs in CI or a container.
- Change only one condition at a time and keep the failing log with each reproduction.
For current Selenium Python installations, a minimal way to capture ChromeDriver’s verbose log is:
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
service = Service(service_args=["--verbose"], log_output="chromedriver.log")
options = webdriver.ChromeOptions()
options.add_argument("--headless")
driver = webdriver.Chrome(service=service, options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()This is a diagnostic starting point, not a universal launch recipe. If the environment is not intended to run headlessly, remove the headless argument. Check your Selenium version’s API if the service constructor differs.
3. Diagnose the common branches
Supplied profile or user-data directory
Temporarily omit the custom profile argument and let the automation session use its own profile. If startup works with a fresh profile but fails with the supplied one, investigate whether that profile is already open, locked, inaccessible to the automation process, or configured in a way that does not suit automation. Check that the configured directory is writable and that separate concurrent sessions do not share it.
A Selenium issue opened in May 2025 reported a Chrome 136 failure with a specified user-data directory that stopped when that argument was omitted. This is a useful isolation clue for profile-dependent failures, not evidence that Chrome 136 generally cannot use profiles. See Selenium issue #15688.
If you need a specific profile’s state, do not treat omitting it as the final fix. Determine why that profile cannot be used safely by this run; consider copying the required state to a separate automation profile rather than having automation and an interactive browser share a live profile.
Managed browser or remote debugging policy
On an organization-managed installation, inspect Chrome’s startup log and policy state. One managed Windows Chrome report included an explicit message that remote debugging was disallowed by the system administrator alongside the port-file error. If your logs indicate a policy restriction, ask the administrator whether the required debugging workflow is permitted. Do not try to bypass the organization’s controls. The report is case-specific: Google Chrome Community discussion.
Headless versus display-backed execution
Verify that the job’s intended mode matches its configuration. A headless job should use the headless mode supported by the browser and automation stack in use; a display-backed job needs its expected display/runtime available. Katalon’s Linux guidance, for example, directs users of its runtime to select its headless Chrome browser mode when that is the intended execution mode. That is Katalon-specific guidance, not a universal Selenium fix: Katalon web automation troubleshooting.
CI, containers, and restricted runtimes
Inspect the actual process environment and the first Chrome error in the logs. Check whether the process can execute the browser binary, write to its temporary and user-data directories, access expected runtime libraries, and use the configured display or headless runtime. In containerized runs, examine the shared-memory and resource configuration reported by the environment. These are checks to investigate from evidence; none is established as the cause of every DevToolsActivePort failure.
Browser and driver paths or versions
Verify which Chrome binary ChromeDriver launched and which driver executable Selenium selected. A machine can contain multiple browser installations or drivers, so a version printed by a shell command may not match the process used in the failing job. Compare the versions and paths from the run itself, then correct a mismatch if the logs establish one. Do not assume version mismatch from this error alone.
4. A repeatable isolation sequence
- Reproduce with logging. Save the full ChromeDriver log and browser stderr, including output before the error.
- Check the executable pair. Record the browser and driver actually launched, their versions, and the Selenium version.
- Try an isolated profile. Use a unique, writable temporary user-data directory for a single run. If this changes the result, focus on the original profile’s ownership, lock, path, and concurrent use.
- Check policy. If the browser is managed or the log mentions remote debugging restrictions, consult the administrator.
- Match runtime mode. Confirm whether the job is meant to be headless or display-backed and configure the relevant automation runtime accordingly.
- Inspect CI/container conditions. Follow concrete log evidence about permissions, writable paths, available resources, and display/runtime setup.
- Retest one change at a time. Keep the previous log and note the single change so the result is reproducible.
5. Flags: avoid cargo-cult fixes
There is no supported universal flags recipe for this message. In particular, adding --no-sandbox, --disable-dev-shm-usage, or a fixed remote-debugging port should not be the first response. A security-weakening flag changes Chrome’s security boundary, and a fixed port may introduce conflicts; only consider a launch argument when evidence from your specific runtime supports it and you understand the effect. The missing-file check itself does not establish that any of these flags is needed.
Likewise, repeatedly changing headless syntax, downgrading Chrome, or removing required profile state without checking logs can hide the trigger without addressing the actual constraint.
6. Troubleshooting table
| What you observe | Likely diagnostic branch | Next action |
|---|---|---|
| Failure goes away when the profile argument is omitted | Profile path, permissions, profile lock, or concurrent use | Try a unique writable profile; inspect the original profile and preserve required state deliberately. |
| Log says remote debugging is disallowed | Managed browser policy | Ask the administrator whether automation using remote debugging is allowed. |
| Local run works, CI run fails | Different binary, user permissions, writable paths, runtime resources, or display/headless setup | Compare actual launch paths, arguments, environment, and first startup errors between runs. |
| Headless run fails but display-backed run works, or the reverse | Execution mode or runtime configuration differs | Confirm intended mode and use the automation vendor’s instructions for that runtime. |
| Only some machines fail | Different installed browser/driver, policy, or host configuration | Capture versions, executable paths, policy state, and verbose logs on both machines. |
| Only the final missing-file message is available | Insufficient startup evidence | Enable verbose ChromeDriver logging and capture browser stderr before changing flags. |
7. Reliability and performance considerations
A reliable automation setup gives each concurrent browser session its own writable user-data directory, records the exact browser and driver paths, and retains startup logs when a session fails. This makes profile collisions and environment differences easier to distinguish. Do not reuse one live profile across overlapping Chrome processes unless the setup explicitly supports that arrangement.
Headless mode is an execution choice, not a guaranteed startup repair. Changing modes, adding flags, or retrying blindly can consume CI time and make a failure harder to reproduce. First identify whether Chrome exited, was blocked by policy, or could not use its profile/runtime. There is no benchmark or universal performance claim implied by this error.
8. Or skip the browser setup
If the task is to obtain a webpage screenshot rather than to run browser automation, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. One GET request returns a PNG, JPEG, WebP, or PDF. The API accepts the URL plus options for full-page or element capture, viewport/device, waits, custom headers and cookies, and other capture settings. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo accepts cookie and consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month, with no card.
9. Frequently asked questions
Does this message mean ChromeDriver is broken?
No. It means ChromeDriver did not find the expected file during startup. The log and launch context are needed to locate the cause.
Should I always add --no-sandbox in CI?
No. It changes a security boundary and is not a general fix established by this error. Use only a change justified by the runtime evidence and your security requirements.
Can I keep using a custom Chrome profile?
Often the profile is simply a useful diagnostic branch. Test with a separate fresh profile, then investigate why the required profile behaves differently and whether it is being used concurrently.
What information should I include when asking for help?
Share the full verbose driver log and browser startup output, OS, browser/driver/Selenium versions, executable paths, launch arguments, whether a custom profile is used, and whether the browser is managed or running in CI/container infrastructure. Remove credentials and private browsing data first.
Can ScreenshotNeo fix a Selenium startup failure?
No. It provides a screenshot API and MCP server for capture tasks; it does not repair ChromeDriver or a Selenium environment. It can avoid setting up a local browser when your goal is simply to capture a page.
