When Selenium’s Chrome headless run suddenly fails, the fix depends on the exact exception and the versions and environment involved. Start by recording your Selenium binding, Chrome, ChromeDriver, operating system, launch mode, and whether the test runs locally, in a container, as a service, or in CI. Then classify the failure as a version mismatch, a headless-mode assumption, an early Chrome crash, driver discovery failure, or Selenium Manager/environment problem.
Start with the failure evidence
Do not begin by adding random flags or reinstalling everything. Save the complete exception, ChromeDriver log, and the values below from the machine that fails:
- Selenium language binding and version (for example, Python package
selenium). - Installed Chrome version and executable path.
- ChromeDriver version and executable path, if you provide one.
- Operating system, CPU architecture, and Linux distribution where applicable.
- Whether the run is interactive, a service, a container, or CI.
- The exact options passed to Chrome, including any legacy headless flag.
“Chrome crashed” and “driver not found” are different failure classes. The exception and startup log determine which branch to follow.
1. Match Chrome and ChromeDriver major versions
Selenium’s Chrome documentation states: “Chromedriver and Chrome browser versions should match, and if they don’t the driver will error.” Check the major number on both sides (for example, Chrome 131 with ChromeDriver 131). A browser that auto-updated while a pinned driver stayed old is a common trigger. See Selenium’s Chrome-specific documentation.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstall#1 Best Overall
- Print the browser version from the installed Chrome binary or About Chrome page.
- Run
chromedriver --versionif a driver executable is on your path. - Compare the major numbers, not just the full patch strings.
- Update the driver or select a browser build whose major version matches it.
- Restart the test process after changing either binary.
The Selenium page describes Selenium 4 as compatible with Chrome 75 and greater by default, but that floor does not replace checking the actual browser/driver pair. Current project context: Selenium 4.49 was released September 9, 2026; a release number alone does not prove that your installed browser and driver are compatible.
2. Replace outdated headless assumptions
Headless is a Chrome launch mode, not a substitute for Chrome, ChromeDriver, or the libraries required by the operating system. Selenium documents Chrome arguments including --headless=new. Chrome’s documentation says, “Chrome now has unified Headless and headful modes.” Since Chrome 132.0.6793.0, the old implementation is available only as the separate chrome-headless-shell binary, rather than being bundled as the legacy mode of the regular Chrome binary. See Chrome Headless mode.
Use current headless Chrome
For a current Chrome installation, configure the normal Chrome binary and use the documented headless argument:
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
options.add_argument("--headless=new")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()Do not interpret the removal of a Selenium convenience method in Selenium 4.10.0 as removal of Chrome headless support. That historical change concerned Selenium’s helper API; Chrome headless remains a browser launch mode.
When the standalone shell is relevant
If an application deliberately depends on the old implementation’s behavior, provision the separately distributed chrome-headless-shell and configure your environment for that binary. Do not point a normal ChromeDriver session at a missing or incorrectly packaged shell. If you do not have a documented dependency on legacy behavior, prefer current unified headless Chrome.
3. Verify that Chrome can start at all
An error such as “Chrome failed to start,” “Chrome exited,” or an immediate crash means the browser process did not stay alive long enough for WebDriver to create a session. Follow ChromeDriver’s startup troubleshooting guidance and preserve the driver log.
Reproduce outside the test harness
Run the same Chrome binary manually with the same profile and relevant arguments. A failure only in CI or a service points toward permissions, a different PATH, missing libraries, a read-only home directory, or a different browser installation. A failure both interactively and under Selenium points more directly to the browser installation or its command-line configuration.
Use only flags that address an observed constraint
Selenium’s example includes --no-sandbox, but that is not a universal security or stability recommendation. Add it only when your container or service design requires it and you understand the isolation trade-off. Likewise, do not add a large collection of “CI flags” without checking the actual log; unnecessary flags can hide the original problem.
Check paths, permissions, and profiles
- Confirm the executable path exists and is executable by the account running the test.
- Use a writable temporary profile when the default profile is locked or inaccessible.
- Make sure the service account has a valid temporary directory and home directory.
- Remove stale user-data directories left by an interrupted run, or assign a unique directory per parallel session.
- Capture ChromeDriver’s verbose log and the browser’s stderr output for the failing run.
4. Fix driver discovery and “unable to locate driver executable”
ChromeDriver is the component Selenium uses to communicate with Chrome. If Selenium reports that it cannot locate the driver executable, solve discovery explicitly instead of treating it as a browser crash. Selenium’s guidance is available at Selenium Manager documentation and ChromeDriver’s driver-location help.
Let Selenium Manager resolve an ordinary installation
When you do not supply a driver, Selenium Manager, included with Selenium releases, acts as a fallback to discover and download a suitable browser and driver. A minimal Python session is:
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
options.add_argument("--headless=new")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
print(driver.current_url)
finally:
driver.quit()This requires Selenium Manager to reach its remote endpoints and to recognize the browser installation. It is not a guarantee for restricted networks, custom Linux packages, or every CPU architecture.
Pin a known driver path for reproducible builds
If your organization controls browser images or blocks downloads, install a matching ChromeDriver in the image and pass its path through Selenium’s supported service object:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.chrome.service import Service
options = Options()
options.add_argument("--headless=new")
service = Service(executable_path="/opt/webdrivers/chromedriver")
driver = webdriver.Chrome(service=service, options=options)
try:
driver.get("https://example.com")
finally:
driver.quit()Choose one management strategy. Supplying a manually pinned driver while expecting Selenium Manager to replace it creates ambiguity and makes upgrades harder to audit.
5. Diagnose Selenium Manager failures
Selenium Manager discovers browser and driver assets from remote endpoints when it is managing them. Its documented failure classes include network errors, custom Linux package managers that require a particular binary, unsupported architectures, and missing shared libraries.
Network, proxy, DNS, or firewall restrictions
If Manager cannot query Chrome for Testing endpoints, inspect proxy and DNS settings from the same user and container that runs the test. In a restricted CI environment, preinstall and pin the browser and driver, then pass the driver path rather than depending on a download during each run.
Custom Linux packages
A distribution may install Chromium or Chrome in a nonstandard location or require a package-specific binary name. Configure the browser binary explicitly and use a driver path managed by your image when Manager cannot identify that package reliably.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Unsupported architecture
Selenium Manager’s documentation identifies Linux arm64/aarch64 and some other architectures as unsupported. On such a host, provision compatible browser and driver binaries yourself, or run the test on an architecture supported by your chosen package source.
Missing shared libraries
A browser can be present yet exit immediately because a dynamic library is absent. The Manager documentation gives libatk-1.0.so.0 as an example and identifies libatk-bridge2.0-0 as the package to install in that described case. Apply that example only when your distribution’s error names the corresponding missing library; it is not a universal remedy for every crash.
6. Compare setup choices before changing production
| Decision | Fallback or current choice | When a pinned or separate choice is better |
|---|---|---|
| Driver management | Selenium Manager resolves assets when no driver is supplied; it is convenient for ordinary installations with network access. | Pin a matching driver path for offline, reproducible builds, custom packages, or unsupported Manager architectures. |
| Headless binary | Use unified headless in the regular Chrome binary with --headless=new. |
Use the separately provisioned chrome-headless-shell only when an application specifically depends on legacy behavior. |
| Execution environment | Interactive local runs usually expose browser paths and libraries directly. | CI, services, containers, and custom Linux images require explicit checks for permissions, libraries, writable profiles, network access, and architecture. |
7. A repeatable repair workflow
- Copy the complete exception and enable ChromeDriver logging.
- Record Selenium, Chrome, ChromeDriver, OS, architecture, and execution context.
- Check Chrome and ChromeDriver major-version compatibility.
- Replace a legacy headless assumption with
--headless=newunless you intentionally provisionchrome-headless-shell. - Run Chrome manually under the same account to separate browser startup from WebDriver discovery.
- Choose either Selenium Manager or an explicitly pinned driver path.
- Check Manager network access, package paths, architecture, and the exact missing-library message.
- Retest with a minimal script against a stable URL before restoring your full test suite.
Common symptoms and precise fixes
| Symptom | Likely class | First fix |
|---|---|---|
| “ChromeDriver only supports Chrome version …” | Major-version mismatch | Update or select a driver matching the installed Chrome major version. |
| “Unable to locate driver executable” | Driver discovery | Allow Selenium Manager to resolve it, or pass a verified executable path; do not use two competing managers. |
| Chrome exits immediately | Browser startup/runtime | Read ChromeDriver logs, verify executable permissions, profile writability, libraries, and environment differences. |
| Manager cannot download assets | Network or policy restriction | Fix proxy/DNS/firewall access or preinstall and pin browser and driver binaries. |
| Works locally but fails in CI | Environment difference | Compare account, paths, architecture, libraries, temporary directories, and network access. |
| Legacy headless behavior disappeared after an upgrade | Headless implementation change | Use unified headless, or intentionally install the standalone chrome-headless-shell. |
Performance and reliability practices
- Build browser and driver versions into the CI image together, then upgrade them as a tested pair.
- Log versions at the start of every run so an automatic browser update is visible.
- Use one temporary profile per parallel session to avoid profile locks and cross-test state.
- Cache approved binaries inside controlled images when outbound downloads are unreliable.
- Keep a minimal startup test separate from application tests; it identifies infrastructure failures earlier.
- Retain driver and browser logs as CI artifacts when a session fails.
Or skip the browser setup
If your actual goal is a clean image or PDF of a URL rather than interactive browser control, ScreenshotNeo provides a website screenshot API. A single GET request returns PNG, JPEG, WebP, or PDF, with browser setup handled by the service.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for all options. Equivalent calls:
Free tools Windows power users keep installed
One-click scans. No signup required.
import 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}`);Before capture, ScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify 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. Create a free ScreenshotNeo account.
FAQ
Does headless mode remove the need for ChromeDriver?
No. Headless changes how Chrome displays its UI; Selenium still needs a compatible browser, driver communication layer, and working runtime environment.
Rank #4
Should I always add --no-sandbox?
No. Match that option to the isolation and permissions of your deployment. Selenium’s example does not make it a universal requirement.
Is Selenium Manager guaranteed to fix every missing-driver error?
No. It is a fallback and can be blocked by network policy, custom packages, unsupported architectures, or missing libraries.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
What should I preserve for a bug report?
Preserve the full exception, ChromeDriver startup log, Selenium/Chrome/driver versions, OS and architecture, launch arguments, executable paths, and whether the run was local, containerized, service-based, or in CI.
Frequently Asked Questions
Does headless mode remove the need for ChromeDriver?
No. Headless changes display behavior; Selenium still requires a compatible browser, driver, and runtime.
Should I always add –no-sandbox?
No. Add it only when your deployment’s isolation and permissions require it.
Is Selenium Manager guaranteed to fix every missing-driver error?
No. Network policy, custom packages, unsupported architectures, and missing libraries can still prevent resolution.
Recommended Free Tools
What should I preserve for a bug report?
Save the full exception, ChromeDriver log, component versions, OS and architecture, launch arguments, paths, and execution context.
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.
