A failed headless screenshot is usually fixed by separating four questions: are Chrome and ChromeDriver compatible, which headless implementation is running, what viewport was requested, and what the driver log says at the failure point. Check those in that order, then treat a missing file, an exception, a blank image and incorrect dimensions as different problems.
Start with a controlled reproduction
Write down the operating system, Chrome version, ChromeDriver version and Selenium version before changing code. The first compatibility check is the major Chrome version against the ChromeDriver major version. Selenium’s Chrome documentation identifies a mismatch as a cause of driver errors.
Record the versions
Run the equivalent version commands on the machine that actually launches the browser:
google-chrome --version
chromedriver --versionOn systems where the executables have different names, use the installed Chrome binary and the ChromeDriver binary configured by your service. Compare the first number in each version. If the majors differ, install a compatible pair before investigating screenshot code.
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
Capture the exact symptom
| What you observe | What to check first |
|---|---|
| No image or no output file | Process exit status, output path, write permissions and driver log. |
| Session or driver exception | Chrome/ChromeDriver major versions, executable paths and startup arguments. |
| Image is blank | Navigation result and page readiness in the script; inspect the log around navigation and capture. |
| Image is clipped or the wrong size | Explicit viewport dimensions and the dimensions reported by the resulting image. |
Official examples show how to request a screenshot, but they do not establish one universal fix for all four outcomes. Keep the original failing image, exception text and log so each change can be evaluated.
Use the correct headless implementation
Chrome’s current architecture uses the same browser code for headless and headful operation. Chrome for Developers describes this as: “Chrome now has unified Headless and headful modes.” That means a recipe written for an older implementation may not describe the binary you are launching.
Current headless Chrome
Use an explicit current-mode argument while diagnosing:
--headless=newMake sure the argument is passed to Chrome, not accidentally treated as a URL or a ChromeDriver option. Keep the rest of the command minimal until a basic page captures successfully.
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
The separate legacy shell
Chrome 132.0.6793.0 is the documented boundary after which the older headless implementation is available as a separate chrome-headless-shell binary. It is not the same executable as ordinary Chrome. Verify the version-specific instructions for any legacy recipe before copying its flags or binary path into a current Selenium setup.
Set a deliberate viewport
Headless sessions do not give you a dependable visual size unless you request one. Chrome’s command-line guidance specifically pairs --screenshot with --window-size to control the capture dimensions.
chrome --headless=new --screenshot --window-size=1280,1000 https://example.comReplace the URL with the page under test. After the command exits, verify that an image was created where your process expects it and inspect its pixel dimensions. If your application has responsive breakpoints, choose a width that deliberately exercises the layout you need rather than relying on a default.
Viewport size is not page readiness
A correct viewport can still produce an empty or incomplete image if navigation has not finished or the page renders content asynchronously. The reviewed Chrome and Selenium documentation does not define a universal delay that fixes every site. Add a readiness condition that belongs to your application—such as the presence of a known element—and diagnose that condition when it fails instead of increasing a fixed sleep indefinitely.
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 & 11Crashes, 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 minuteRank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
Enable ChromeDriver logging
Selenium exposes driver logging through its Service class. Send the log to a file during diagnosis and read the lines surrounding startup, navigation and screenshot capture. Logging often distinguishes a session-creation failure from a page-level failure that occurs after the session is already running.
Python Selenium example
from pathlib import Path
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.chrome.service import Service
url = "https://example.com"
options = Options()
options.add_argument("--headless=new")
options.add_argument("--window-size=1280,1000")
service = Service(log_output="chromedriver.log")
driver = webdriver.Chrome(service=service, options=options)
try:
driver.get(url)
driver.save_screenshot("shot.png")
print("viewport:", driver.get_window_size())
print("saved:", Path("shot.png").resolve())
finally:
driver.quit()This script intentionally does not claim that a fixed wait solves blank pages. If the target is dynamic, add an explicit, site-specific wait after get, then record which condition was awaited and whether it was found. Keep the log enabled until the capture is stable.
Check the log, not just the exception
- If the log stops during session creation, return to version, executable-path and startup-argument checks.
- If session creation succeeds but navigation fails, examine the URL, network access and the page’s own readiness condition.
- If navigation succeeds but capture fails, confirm that the screenshot path is writable and that the browser process remains alive until the save call completes.
Fix each failure mode
“Session not created” or a driver-start error
- Compare Chrome and ChromeDriver major versions.
- Confirm that the service points to the executable you just version-checked.
- Remove copied legacy flags and start with
--headless=new. - Run again with a driver log file and use the first startup error as the next diagnostic target.
Changing the screenshot API will not repair an incompatible browser session; the browser must start successfully first.
The command exits but no image appears
- Use an absolute or clearly resolved output path while testing.
- Check the process exit status and the driver log.
- Confirm that the process reaches the save operation and that the destination directory is writable.
- Run the minimal
--screenshot --window-sizecommand against a simple URL to separate browser startup from application-page behavior.
The image is blank
Do not assume that “blank” means the same thing as a driver crash. Confirm that navigation reached the intended URL, inspect the page state in the script, and wait for an application-specific element when the page renders asynchronously. Save the log and the URL used. There is no documented universal wait duration or guaranteed blank-image workaround.
Recommended Free Tools
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
The image is clipped or dimensions are unexpected
Set --window-size=width,height (or the equivalent browser option), then print the reported window size and inspect the image’s actual pixel dimensions. Remember that a viewport size is not automatically a full-page height; if your requirement is a complete long document, define how your application will capture that document and verify the resulting dimensions rather than assuming a default.
A legacy tutorial no longer works
Check its assumptions against your installed Chrome version. Since Chrome 132.0.6793.0, the older headless mode is distributed as chrome-headless-shell. A command that names an old binary or old headless flag may be targeting a different implementation from the one on your machine.
A repeatable diagnostic workflow
- Freeze the evidence. Record OS, Chrome, ChromeDriver and Selenium versions; keep the failing URL, command and output.
- Prove compatibility. Align Chrome and ChromeDriver major versions and verify the executable paths.
- Identify headless mode. Use current headless Chrome explicitly, or document that you intentionally use the separate legacy shell.
- Control geometry. Set a known window size and measure the image that was produced.
- Turn on logs. Route ChromeDriver output through Selenium’s
Serviceclass and inspect the first error at the point of failure. - Reduce the page. Capture a simple URL, then add your application URL, waits and custom options one at a time.
- Make readiness explicit. For dynamic pages, wait for a page-specific condition and record whether it was met.
- Retest from a clean process. Close the driver in a
finallyblock so a failed run does not leave a confusing session behind.
Reliability and maintenance practices
- Pin and document the Chrome/ChromeDriver pairing used by your build or deployment image; re-check the major-version match after browser updates.
- Keep a fixed viewport for visual regression jobs so a layout change is not confused with a window-size change.
- Retain logs for failed runs and the image dimensions for successful runs. This gives you evidence when a blank page and a clipped page look similar at a glance.
- Keep startup arguments minimal. Add blocking, custom profiles or other flags only after a basic capture works, so a new failure has a small search area.
- Use a page-specific readiness signal rather than a universal sleep. Different applications load different resources and expose different stable elements.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server when you want an HTTP call instead of maintaining a ChromeDriver session. It removes cookie and consent banners, newsletter popups and chat widgets before capture; bot checks, blank pages, failed loads and timeouts are not billed, and each response reports the page verdict and billing status in headers. Its MCP tools—take_screenshot, get_page_info and capture_pdf—let Claude, Cursor and other MCP clients request captures.
Every feature is available on every plan, including full-page capture with lazy images loaded, CSS-selector element capture, dark mode, device presets and custom viewports, retina scale, PDF paper and page-range controls, custom CSS and JavaScript, pre-capture clicks, hidden selectors, selector/delay/network-idle waits, request and resource blocking, custom headers/cookies/user agents/Authorization, timezone and geolocation, transparent backgrounds, resizing, chosen-TTL caching, signed image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API and an OpenAPI specification.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →One call with cURL
See the ScreenshotNeo API documentation for the complete option list.
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
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}`);The Free plan includes 1,000 shots per month with no card. Paid plans are Starter $5 for 3,000 shots, Growth $15 for 15,000, Pro $39 for 60,000, Scale $99 for 250,000 and Business $249 for 1,000,000; yearly billing gives two months free. Create a free ScreenshotNeo account to start without a card.
Frequently Asked Questions
Should I switch from Selenium immediately when a screenshot fails?
No. First establish a working browser session, matching major versions, a known viewport and a useful ChromeDriver log. An API is an alternative when you prefer not to operate that browser setup.
Why can two captures of the same URL have different layouts?
A responsive page can select different layouts for different viewport dimensions. Set and record the viewport explicitly before comparing images.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →What information should I include when asking for help?
Include the operating system, Chrome and ChromeDriver versions, Selenium version, exact headless arguments, URL, symptom type, image dimensions and the relevant ChromeDriver log lines.
The Bottom Line
Match ChromeDriver to Chrome, identify the headless implementation, set the viewport explicitly and use Service logging to locate the failing stage. Then fix the symptom you actually have—startup, output, readiness or dimensions—instead of applying a generic screenshot workaround.
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.
