Free tools Windows power users keep installed
One-click scans. No signup required.
To fix Selenium headless-mode errors on Linux, first identify whether Chrome itself can start, then check the Chrome/ChromeDriver versions, user permissions, runtime libraries, and driver discovery. Headless Chrome does not normally need Xvfb; adding flags at random can hide the cause rather than fix it.
Start with the failure layer
Headless mode removes the visible browser window. It does not remove Chrome’s need for a working browser binary, a compatible driver, and the Linux runtime libraries Chrome depends on. Diagnose in this order so each result narrows the cause.
- Record the first complete error. Save the exception, ChromeDriver log, Chrome and ChromeDriver versions, browser path, and arguments passed by the test.
- Try launching the exact Chrome binary directly. Use the same Linux account and environment as the test. If Chrome fails outside Selenium, resolve that installation or environment failure before changing WebDriver settings.
- Check version compatibility and driver discovery. Confirm the selected ChromeDriver supports the installed Chrome version, and establish which driver and browser Selenium actually selected.
- Check the execution user and named missing libraries. Do not assume a generic flag or package addresses a different error.
ChromeDriver’s troubleshooting guide identifies running Chrome as root as a common startup-crash cause. It says the --no-sandbox workaround is unsupported and highly discouraged. Prefer running Chrome as a regular Linux user and correcting the container or service setup.
Check Chrome and ChromeDriver versions
Selenium’s Chrome documentation says Chrome and ChromeDriver major versions should match. An error such as “This version of ChromeDriver only supports Chrome version …” points to a compatibility mismatch, not a headless-specific failure. Check the major version of the browser and the driver executable Selenium is using; a separately installed driver may be taking precedence over the one you expected.
#1 Best Overall
For standard Selenium bindings, Selenium Manager is built in and used by default to manage browser drivers. It is generally the simplest route when the environment supports its downloads. If you use a custom package manager, a managed image, or a network that blocks downloads, explicitly configure browser or driver locations and keep the versions compatible. Selenium Manager’s behavior and supported environments are documented at Selenium Manager.
Choose a management approach
| Approach | When it fits | What to check |
|---|---|---|
| Selenium Manager | Standard supported Selenium setup where automatic browser/driver management is permitted. | Network and proxy access for downloads, plus the exact error if management fails. |
| Explicit paths | Custom package managers, controlled images, or installations where versions and locations are pinned. | The actual browser and driver paths selected at runtime, their compatibility, and who maintains updates. |
Do not download another driver or change paths until the error indicates that driver management or discovery is the problem. For example, “Unable to locate the chromedriver executable” is a discovery/path issue; it does not by itself show that headless mode is broken.
Rank #2
Confirm the binary and arguments Chrome receives
Use ChromeDriver’s guidance to launch the same Chrome binary used by the test from a normal user command line. Check the ChromeDriver log for the selected binary and preserve the arguments used in the failing test. If direct Chrome launch fails, fix that first. If direct launch works but WebDriver does not, investigate driver compatibility, the service log, and differences in the test harness or environment.
Enable ChromeDriver service logging before changing multiple variables. Selenium’s Chrome documentation shows how to send service output to a file or standard output and configure logging. Keep the log with the browser path, version numbers, arguments, and the full first startup error; this makes startup failures such as “DevToolsActivePort file doesn’t exist” diagnosable instead of guessing that one particular flag is responsible.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsUse headless mode without a display server
Selenium documents Chrome headless arguments including --headless=new. Chrome’s headless documentation explains that Chrome creates platform windows without displaying them, and its headless shell documentation says a display server such as Xvfb is not needed for headless Chrome. A machine without a desktop session is therefore not, by itself, a reason to install Xvfb.
Use a visible session only as a comparison where a display is available: run the same binary and arguments headful, then compare the direct Chrome result with the WebDriver result. Avoid changing several launch arguments at once. For version-specific options, use the current Selenium and Chrome documentation rather than assuming an old flag remains appropriate.
Resolve missing Linux runtime libraries
If the error says error while loading shared libraries, act on the library named in that message. Selenium Manager’s Linux example reports libatk-1.0.so.0 as missing and identifies libatk-bridge2.0-0 as the package to install for that example. Package names differ among distributions; use the package manager and package name appropriate to your Linux distribution. That example package is not a general fix for unrelated errors or every Linux system.
Troubleshoot common messages
| Message or symptom | Likely area | Next step |
|---|---|---|
| “DevToolsActivePort file doesn’t exist” | Chrome failed during startup; the message alone does not identify why. | Launch the exact binary directly as the same user, then inspect ChromeDriver’s startup log, arguments, and environment. |
| “This version of ChromeDriver only supports Chrome version …” | Browser/driver compatibility. | Compare Chrome and ChromeDriver major versions and verify which executable Selenium selected. Check Selenium Manager or correct explicit paths. |
error while loading shared libraries: libatk-1.0.so.0: cannot open shared object file |
A missing runtime library. | Install the distribution-appropriate package for the named library; Selenium’s documented example identifies libatk-bridge2.0-0 for this case. |
| “Unable to locate the chromedriver executable” | Driver discovery or path configuration. | Check Selenium Manager’s download access or configure the correct explicit driver path for the installation. |
| Chrome crashes when launched by a service running as root | Execution user and sandbox configuration. | Run Chrome as a regular Linux user. ChromeDriver describes --no-sandbox as unsupported and highly discouraged. |
| Automatic driver/browser setup cannot download | Network, proxy, package-manager, or environment constraints. | Check download access and proxy settings; if necessary, use a controlled browser and compatible driver at explicit paths. |
Or skip the browser setup
If your goal is a website screenshot rather than browser automation, ScreenshotNeo offers a one-request screenshot API and an MCP server for AI agents. Cookie banners, popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are never billed. Its MCP tools let AI agents take screenshots, and 1,000 shots a month are free with no card; paid plans start at $5 for 3,000.
cURL example, using the documented API pattern with a target URL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
See the ScreenshotNeo documentation for setup and options. Sign up for 1,000 free screenshots a month with no card.
Frequently Asked Questions
Does Selenium headless Chrome require Xvfb on Linux?
No. Chrome’s headless shell documentation says a display server such as Xvfb is not needed for headless Chrome.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Does “DevToolsActivePort file doesn’t exist” identify one specific broken flag?
No. It is a startup failure symptom; the ChromeDriver log and direct launch of the selected binary are needed to narrow the cause.
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.
