How to Fix Chrome Browser Issues in Selenium
Fix Selenium and Chrome failures by checking the browser and driver versions, executable paths, startup options, and runtime environment in a practical order.
When Selenium cannot start or control Chrome, first check the actual Chrome and ChromeDriver versions and executable paths used by the failing process. Their major versions must match. Then check whether Selenium Manager can resolve the driver, and investigate Chrome startup options and the environment where the test runs.
This order distinguishes the common compatibility and setup problems without treating a particular error message as a diagnosis. The examples below use Python; equivalent setup guidance for cURL, Python, and Node.js follows where relevant.
1. Record the versions and paths Selenium actually uses
Before changing flags or reinstalling packages, collect the browser version, driver version, Selenium binding version, and paths. A driver can be installed but not be the one selected by PATH or an explicit service configuration.
- Open
chrome://versionin the Chrome installation used by the test to inspect its version and browser details. - In the same shell or runner that launches the test, inspect available executables:
which google-chrome,which chromium, andwhich chromedriveron Linux/macOS, or usewhereon Windows. - Check the versions:
google-chrome --version(or the browser executable’s equivalent),chromedriver --version, andpython -m pip show selenium. - Compare Chrome and ChromeDriver at the major-version level. For example, Chrome 126 and ChromeDriver 126 are a matching major pair; Chrome 126 and ChromeDriver 113 are not.
For Chrome 115 and newer, Google directs users to Chrome for Testing release data to find corresponding Chrome and ChromeDriver releases. See ChromeDriver and Chrome for Testing and Selenium’s Chrome-specific documentation.
A familiar mismatch error is “This version of ChromeDriver only supports Chrome version 113”. If Chrome updated automatically while the project kept a manually pinned driver, update the pair or remove the unnecessary pin.
2. Use Selenium Manager or pin a matching pair
Selenium Manager ships with Selenium releases starting at 4.6. When the binding has not already been given a driver, it can discover the browser, resolve a compatible driver, and download and cache it. This is the simplest routine path when the machine can reach Selenium’s metadata and download sources.
Python with Selenium Manager
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
# Optional for a headless CI run:
# options.add_argument("--headless=new")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
print("Title:", driver.title)
finally:
driver.quit()Install or update the Selenium binding with python -m pip install --upgrade selenium. Remove an old explicit ChromeDriver path if you intend Selenium Manager to select the driver. Manager is a fallback; it does not override a driver already supplied to the binding.
When explicit version management is the better fit
Pin Chrome and ChromeDriver together when repeatable CI builds require a known browser/driver pair, or when the environment needs special executable paths. Make both versions visible in the build configuration and update them as a pair. If you supply a driver path, verify that the file exists and is executable to the test’s runtime user.
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from selenium.webdriver.chrome.options import Options
options = Options()
# Set this only when Chrome is not at the system-discovered location.
options.binary_location = "/usr/bin/google-chrome"
service = Service(executable_path="/usr/local/bin/chromedriver")
driver = webdriver.Chrome(service=service, options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()Replace those paths with the actual paths on the machine running the test. An incorrect explicit path can defeat automatic resolution and select an incompatible or missing binary.
3. Check driver discovery and executable permissions
If Selenium says it cannot locate a driver executable, inspect PATH and every explicit driver setting, including a Selenium service object or system property. Confirm the configured file exists and can be executed by the same account that runs the test. See Selenium’s driver-location troubleshooting.
For additional diagnostics, enable Selenium Manager logging using its documented configuration and inspect the messages showing browser discovery, driver resolution, and cache behavior. Do not infer the selected path from a different terminal session: IDEs, services, containers, and CI jobs can have different PATH values.
4. Diagnose Chrome that exits or fails to start
A launch that works in an interactive terminal can fail in an IDE, test harness, CI runner, or background service. Reproduce the launch under the same user and environment as the failing test, then compare:
- Chrome binary path and the command-line options Selenium supplies.
- User identity and permissions for the browser executable and profile directory.
- Environment variables and runtime resources available to the test process.
- Whether another session is using the same custom profile directory.
Use a separate profile directory for simultaneous sessions. Selenium documents setting a custom profile with --user-data-dir; choose a directory appropriate to that run. Its Chrome options documentation also covers headless operation with --headless=new.
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
options.add_argument("--headless=new")
options.add_argument("--user-data-dir=/tmp/selenium-chrome-profile-run-1")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()Do not add --no-sandbox as a routine fix. ChromeDriver describes it as an unsupported and highly discouraged workaround. Only consider it when a specific, understood environment requires it. See Chrome doesn’t start or crashes immediately.
5. Treat DevToolsActivePort as a symptom
DevToolsActivePort file doesn't exist does not identify one universal cause. Check version compatibility, whether Chrome can start in the failing environment, the selected binary and options, and the user/profile context. If direct Chrome launch fails, investigate the browser runtime. If it succeeds, compare the exact launch arguments and environment used by ChromeDriver. Avoid assuming one flag fixes every instance.
6. Handle proxies, Linux packages, and architecture limits
Selenium Manager needs remote metadata and downloads. A proxy or firewall can interrupt resolution. Configure the documented proxy support, including SE_PROXY where appropriate, and allow the required metadata and download endpoints. If the network cannot be opened, manage a compatible browser/driver pair explicitly and set their paths.
Package-managed Linux browsers may need explicit browser and driver locations, particularly when the package’s executable layout differs from Selenium’s discovery assumptions. Selenium documents that its Linux Manager build is verified for x64 and does not support Linux arm64/aarch64, 32-bit systems, or Raspberry Pi under its stated support model. In those environments, plan on explicit compatible binaries or another supported setup. Details and current configuration names are in the Selenium Manager documentation.
7. Choose the setup that matches the environment
| Approach | Best suited to | Trade-off |
|---|---|---|
| Selenium Manager fallback | Local development and runners with access to metadata/download sources | Less manual version bookkeeping; relies on network access and supported platform behavior |
| Explicitly managed pair | Reproducible CI, restricted networks, or special browser packages | Known versions and paths; your project owns updates and compatibility |
Both approaches still need a compatible Chrome and ChromeDriver major version. Keep the chosen strategy consistent across developer machines and CI so a local success does not conceal a runner-specific configuration problem.
8. Common errors and fixes
| Symptom | Likely area to inspect | Practical next step |
|---|---|---|
| “This version of ChromeDriver only supports Chrome version …” | Major-version mismatch, often after Chrome updated | Update the driver to match Chrome, or pin and update both as a pair. For Chrome 115+, consult Chrome for Testing release data. |
| “Unable to locate driver” or driver executable missing | PATH, explicit service path, permissions, or a different runtime account | Inspect the actual process PATH and configured path; verify the file exists and is executable. Consider removing the explicit path to use Manager. |
| “Chrome failed to start” or immediate crash | Browser path, options, profile, or execution environment | Reproduce with the same user and environment; compare paths, options, permissions, profile use, and available runtime resources. |
DevToolsActivePort file doesn't exist |
Chrome startup or environment; message alone is not a diagnosis | Check versions and launch context, then compare direct Chrome startup with ChromeDriver’s command and profile settings. |
| Manager cannot resolve or download a driver | Proxy/firewall, metadata access, or unsupported platform | Configure proxy access and required endpoints, or provide explicit compatible browser and driver paths; verify platform support. |
9. Performance, reliability, and maintenance
- Cache and repeatability: Selenium Manager caches resolved downloads, so subsequent runs need not repeat the initial download. A pinned pair makes browser changes explicit, but requires regular paired updates.
- Startup time: The first Manager resolution may need network access and a download. In CI, prepare the environment or cache according to your runner’s supported persistence model, and distinguish driver setup time from page-load time when diagnosing slow tests.
- Parallel runs: Do not have concurrent sessions share one custom Chrome profile. Give each run its own profile directory and always call
quit()in cleanup so browser processes are released. - Reliability: Record browser, driver, Selenium, paths, and relevant options in failure logs. Reproduce with the same account and environment before adding launch flags.
- Cost: Selenium and ChromeDriver are software components; the reviewed setup guidance does not establish a per-session service price. Budget for CI compute, network access, and the engineering work of keeping pinned binaries current.
10. Or skip the browser setup
If your task is to capture a website image or PDF rather than automate an interactive browser test, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns an image or PDF. See the 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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; each cleaning step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, with page verdict and billing information in response headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Every feature is available on every plan.
Sign up free for 1,000 screenshots a month, with no card required.
FAQ
Does Selenium Manager replace Chrome?
No. It manages driver resolution and can detect the installed browser; Chrome still needs to be installed or otherwise available in the environment.
Should I upgrade Selenium first?
If the binding is old, upgrading to a current Selenium release gives you Selenium Manager support and current fixes. Still verify the selected browser and driver afterward.
Can a successful local run prove CI is configured correctly?
No. The CI process can have different binaries, PATH, user permissions, network access, profile state, and runtime resources. Inspect those from the runner itself.
Is Selenium a substitute for a screenshot API?
Use Selenium when you need browser interaction and test control. For a capture-only task, a screenshot API can avoid managing a browser and driver in your own process.
