There is no universal GPU flag that fixes every headless Chrome crash. First identify whether ChromeDriver, Chrome during startup, or Chrome’s --type=gpu-process child is failing. Then reproduce the failure with the exact Chrome binary and switches, inspect the active command line and chrome://gpu, and only then choose a platform- and version-specific remedy.
Identify which process actually crashed
Automation logs often call every failed session a “ChromeDriver crash,” but the remedies differ:
- ChromeDriver executable crash: the driver process itself terminates.
- Chrome startup failure: Chrome never creates a usable browser session or exits immediately.
- GPU subprocess crash: Chrome starts, but a child launched with
--type=gpu-processrepeatedly exits or causes the browser to close.
ChromeDriver’s troubleshooting guide explicitly separates its own crash from Chrome crashing or closing. Record the failing process, the time of failure, and the complete test-harness error before changing flags. See Chrome’s startup and ChromeDriver troubleshooting guidance.
Capture a reproducible baseline
- Record the exact Chrome and ChromeDriver versions, operating system and distribution, Chrome binary path, container or virtual-machine details, and the full argument list supplied by your framework.
- Find the binary your test actually launches. Do not assume it is the system default; Selenium, CI images and wrappers can select another installation.
- Launch that same binary directly as the same operating-system user, outside the test harness, with the same headless and graphics switches. For example, adapt the path and URL to your machine:
/path/to/chrome --headless=new --remote-debugging-port=9222 https://example.com - Compare the result. If direct Chrome also fails, investigate the browser installation, drivers and runtime first. If direct Chrome works, compare the harness environment, inherited variables, permissions and arguments.
Modern Headless is Chrome itself running without visible UI. Since Chrome 112 it creates platform windows without displaying them; the older Headless implementation was separate. This distinction matters when comparing old launch recipes with current Chrome. Read the current Headless mode documentation.
Inspect the switches Chrome really used
In the affected browser instance, open chrome://version and copy the complete command line. This is more reliable than a configuration file or a remembered framework default. Chromium notes that chrome://flags may not accurately show whether a command-line switch is active; use the command line as the source of truth. The procedure is documented in Chromium’s command-line-switch guide.
Save the command line with your bug record. Pay particular attention to duplicate switches, a different --user-data-dir, an unexpected binary, and flags injected by a container image or test runner.
Inspect graphics detection and the renderer
Open chrome://gpu in the same Chrome build and save the report. Check:
- the renderer name (hardware GPU, SwiftShader, lavapipe or another software renderer);
- Graphics Feature Status, including WebGL, WebGPU and compositing;
- the Problems Detected and Driver Bug Workarounds sections;
- whether the report changes between a normal launch and the failing headless launch.
Chrome’s GPU guidance uses this report to determine whether hardware graphics are available. A Linux example describes an NVIDIA T4 that was not detected until compatible drivers were installed. That demonstrates driver detection, not a guaranteed cure for every GPU-process crash. See Chrome’s WebGPU, WebGL and Headless Chrome guidance.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Check Linux permissions, sandboxing and the driver stack
On Linux, collect the distribution and kernel, container or VM type, GPU-device access, Mesa or vendor-driver versions, Vulkan availability, and whether Chrome selected SwiftShader or lavapipe. A missing device, incompatible loader or software-rendering path can fail differently from a hardware-driver failure.
Also check the account running Chrome. ChromeDriver identifies running Chrome as root as a common cause of immediate startup crashes. Use a regular user whenever possible. Its documentation calls --no-sandbox unsupported and highly discouraged because it weakens a key security boundary. Do not add it as a routine “fix”; correct the user, container permissions and sandbox prerequisites instead.
Choose a remedy that matches the evidence
Chrome exits when run as root
Run the job under a non-root user with a writable profile and the required shared-memory and device permissions. Remove --no-sandbox unless you are performing a tightly isolated diagnostic experiment and understand the security consequence. A setting that makes a CI job start by disabling the sandbox is not a safe production solution.
GPU acceleration is required but the report is software-only
Validate the platform’s driver and loader installation first. Compare chrome://gpu before and after the change, and verify that the renderer and feature status now match the workload’s requirements. Chrome’s Linux GPU-enabled example uses --headless=new, --use-angle=vulkan, --enable-features=Vulkan and --disable-vulkan-surface. Treat those as an example for that documented setup, not a generic crash recipe; apply them only after confirming that your Chrome version, driver and workload support the same path.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchRank #3
The workload does not need GPU acceleration
As a controlled diagnostic, test a GPU-disabled launch for the specific Chrome version and operating system:
/path/to/chrome --headless=new --disable-gpu https://example.com
Compare direct launch and the automated run, and record the result. Do not promise that this switch prevents GPU-process crashes. A recent report for Linux software rendering with Mesa lavapipe and LLVM on M151 says --disable-gpu was insufficient in that case. The report is version- and environment-specific, and its status can change; it is not evidence that every M151 installation, or every Chrome release, behaves the same way. See Chromium issue 536977900.
A software Vulkan loader fails inside the GPU process
The same M151 report mentions --disable-gpu-sandbox as a diagnostic workaround for one LLVM-loader failure. It is not established as a generally supported production setting. Use it only to isolate the cause in a disposable environment, then fix the loader, driver or sandbox interaction and remove the flag. Never use it to conceal an unresolved security or compatibility problem.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteOld Windows advice conflicts with current behavior
A historical Headless Chrome shell guide said --disable-gpu was temporarily necessary on Windows and that other platforms no longer required it. Preserve that platform and time context when reading old scripts; do not transplant the advice into a current Linux or Windows diagnosis without testing the exact Chrome build. The historical note is at Headless Chrome shell.
Keep the test harness from hiding the cause
- Run one failing URL or test with a fresh, dedicated profile.
- Log the exact ChromeDriver command and Chrome launch arguments.
- Keep ChromeDriver, Chrome and the automation library versions together in the log.
- Capture Chrome’s stderr and ChromeDriver’s verbose log, including the final lines before the GPU child exits.
- Repeat with the same user, environment variables and filesystem mounts used by CI.
- Do not change several graphics flags at once; otherwise you cannot identify which condition mattered.
If Chrome works directly but not through the harness, compare process limits, shared-memory mounts, device visibility, profile locking and injected flags before changing rendering settings.
Common symptoms and targeted checks
| Symptom | Likely stage | Next check |
|---|---|---|
| ChromeDriver binary disappears | Driver process | Driver version, executable permissions, driver log and a minimal driver-only reproduction |
| Chrome closes before a session is created | Chrome startup | Direct launch with the same binary and arguments; user, profile and sandbox setup |
| Session starts, then GPU child repeatedly exits | GPU subprocess | chrome://gpu, renderer, driver/loader versions and crash timing |
| Only a container or VM fails | Environment | GPU-device access, Vulkan/Mesa stack, shared memory and inherited flags |
--disable-gpu changes nothing |
Version-specific or software-rendering path | Check the active command line and compare with the M151 lavapipe report |
Build an actionable bug report
When the failure remains reproducible, provide a minimal test and state whether direct Chrome launch also fails. Include:
- Chrome and ChromeDriver versions and the exact binary paths;
- OS, kernel, container or VM details, user identity and relevant permissions;
- the complete command line from
chrome://version; - the full
chrome://gpureport, including renderer and problems; - Chrome and ChromeDriver logs and the crash timestamp;
- the smallest URL or script that reproduces the failure; and
- which flags were tested and what changed.
ChromeDriver’s official guidance recommends supplying a reproducer and filing a bug when the issue persists. This evidence lets maintainers distinguish a driver defect from a Chrome, graphics-stack or environment problem.
Or skip the browser setup
If your goal is simply to obtain reliable website screenshots rather than debug a local ChromeDriver environment, ScreenshotNeo provides a GET-based screenshot API and an MCP server for AI agents. It accepts consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; failed loads, bot checks or CAPTCHAs, blank pages, timeouts and cache hits are not billed, and response headers identify the page verdict and billing result.
One request returns PNG, JPEG, WebP or PDF. The API supports full-page lazy-image loading, CSS-selector element capture, dark mode, device presets and custom viewports, retina scale, PDF page settings, custom CSS and JavaScript, pre-capture clicks, waits, blocked requests, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting and an OpenAPI specification. Its parameter names are compatible with those used by other screenshot APIs.
cURL (see the ScreenshotNeo documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
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)Node.js:
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 includes take_screenshot, get_page_info and capture_pdf tools through MCP for Claude, Cursor and other MCP clients. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.
Frequently Asked Questions
Should I always add --disable-gpu to headless Chrome?
No. Test it only as a controlled diagnostic for the exact Chrome version and platform; documented failures exist where it did not stop a software-rendering GPU crash.
Does --no-sandbox fix a root-user crash safely?
It may mask a startup condition, but ChromeDriver documents it as unsupported and highly discouraged. Run Chrome as a regular user and correct the runtime instead.
What proves that the GPU driver is the cause?
A changed chrome://gpu renderer or feature report together with a direct-launch reproduction and matching driver/loader evidence is stronger than a crash disappearing after an unrelated flag change.
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.
