Why Is My Selenium Screenshot Completely White?
A white Selenium screenshot can come from a blank page, a capture taken too early, or a browser and driver mismatch. Use this checklist to isolate the cause.
A completely white Selenium screenshot does not point to one universal bug. First check whether the browser itself is blank immediately before capture. If it is, investigate navigation and page rendering. If the browser shows the expected content but the PNG is white, investigate when and how the screenshot is captured, then compare browser and driver environments.
A successful screenshot call only tells you that WebDriver returned image data for the current browsing context. It does not prove that the page had rendered the content your test expected. Selenium documents screenshots as captures of the current window or browsing context. Selenium: Working with windows and tabs
1. Find out whether the page or the screenshot is blank
Before changing browser flags or adding delays, inspect the live browser and the exact file produced by the current run. Record what the page shows immediately before the screenshot call.
- Check the current URL and page title.
- Inspect the page source or verify that an expected element or text is present.
- Look at the browser window immediately before capture, if the run is visible.
- Open the PNG saved by this run and confirm it is the file you are inspecting.
If the browser is blank too, the screenshot is probably reflecting the current page state; troubleshoot navigation, redirects, application errors, and rendering first. If the browser looks correct but the file is blank, focus on capture timing, the active browsing context, and the browser/driver setup. This split is a practical diagnostic inference from Selenium’s description of screenshots as captures of the current context.
2. Wait for meaningful page content
driver.get() returning is not a guarantee that a JavaScript application has finished rendering. Selenium’s default page-load behavior waits for a readyState value of complete, but scripts can continue changing the page after that point. The right wait is for the content your screenshot actually needs, such as a visible main region, a chart, or a page-specific ready marker.
Selenium recommends explicit waits for conditions that must become true. Its documentation also warns that mixing implicit and explicit waits can produce unpredictable wait times. Prefer one clear waiting strategy for this capture. Selenium: Waiting Strategies
Runnable Python example
Install Selenium with python -m pip install selenium, ensure a compatible browser is installed, and replace the URL and selector with the page and visible content that signal readiness in your application.
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait
options = webdriver.ChromeOptions()
options.add_argument("--headless")
options.add_argument("--window-size=1440,1000")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
wait = WebDriverWait(driver, 15)
wait.until(EC.visibility_of_element_located((By.CSS_SELECTOR, "main")))
driver.save_screenshot("screenshot.png")
finally:
driver.quit()The selector and timeout are examples, not universal values. Choose an element that appears only when the screen is ready for your use case. If a page has no reliable element, wait for a meaningful application condition rather than assuming a fixed delay will work for every run.
3. Make headless Chrome’s viewport and timing intentional
For headless Chrome, set a known window size and wait for the same meaningful page condition you use in a visible run. An unexpected viewport can change responsive layout and what is visible. Chrome’s headless command-line reference shows screenshots with --window-size and documents --timeout as a maximum wait before capture, even if loading may still be in progress. That timeout does not prove your app has reached the state you need; use a Selenium explicit wait for that.
Chrome for Developers: Headless command-line reference
Optional command-line comparison
To compare Selenium with Chrome’s own headless screenshot path, run this from a shell with Chrome available. It saves screenshot.png in the current directory:
chrome --headless --window-size=1440,1000 --timeout=10000 --screenshot="screenshot.png" "https://example.com"Use this as a diagnostic comparison, not as proof that a fixed timeout is sufficient for a dynamic application.
4. Compare browser modes and check versions
Run the same URL and application state in a visible session, then in headless mode. If possible, compare another browser as well. Selenium’s troubleshooting guidance recommends addressing synchronization and trying commands in multiple browsers to help rule out a driver-specific problem. A comparison narrows the search; it does not by itself identify the faulty component.
For Chrome, record the Chrome and ChromeDriver versions and confirm their major versions match. Selenium’s Chrome documentation identifies matching major versions as a compatibility requirement. Also record the Selenium version, operating system, headless or headed mode, viewport, URL, and relevant browser or driver logs when investigating a reproducible issue. Selenium: Troubleshooting Assistance · Selenium: Chrome specific functionality
5. Check the screenshot file and browsing context
Selenium captures the current window or browsing context. If the page looks right but the image does not, confirm that your code is capturing the tab and window you expect. Then verify that save_screenshot succeeded, inspect the file written by this run, and check whether a later test step or process replaces it.
For a quick Python diagnostic, print the current URL and title just before saving:
print("URL:", driver.current_url)
print("Title:", driver.title)
print("Main visible:", driver.find_element(By.CSS_SELECTOR, "main").is_displayed())
print("Saved:", driver.save_screenshot("screenshot.png"))This example assumes the page has a main element. Change the selector to match your page. The return value helps confirm the save call, while inspecting the resulting file confirms what was actually written.
6. Common causes and fixes
| Symptom | Likely area to inspect | What to do |
|---|---|---|
| Browser and PNG are both blank | Navigation, redirect, application state, or page rendering | Check URL, title, source, expected content, and browser logs before changing screenshot code. |
| PNG is blank, but visible browser is correct | Capture timing, wrong tab/window, or output file handling | Wait for visible page content, confirm the current context, and inspect the file saved in this run. |
| It fails intermittently on a dynamic page | Synchronization | Replace an assumed navigation-complete signal or default fixed sleep with an explicit wait for a page-specific visible condition. |
| Headless output differs from visible output | Viewport and execution environment | Set a deliberate window size and compare the same URL and state in both modes. |
| Chrome session or commands fail unexpectedly | Chrome and ChromeDriver compatibility | Check that their major versions match and note all relevant versions and logs. |
| The image looks like an old or unrelated page | Wrong file or later overwrite | Use a distinct output path per run and verify no later step replaces the file. |
The available official documentation supports checks for readiness, current-context capture, headless viewport and timeout, cross-browser diagnosis, and Chrome/ChromeDriver compatibility. It does not establish a universal white-screenshot bug or a general diagnosis involving GPU settings, sandbox flags, a particular operating system, or a specific Selenium release. Treat those as case-specific hypotheses only when your own evidence points there.
7. Avoid timing fixes that hide the problem
- Use an explicit condition: wait for the exact content that must appear in the image.
- Do not default to a long sleep: a delay may still be too short on a slow run and waste time on a fast one.
- Do not mix implicit and explicit waits casually: Selenium warns that the resulting wait durations can be unpredictable.
- Keep the capture reproducible: use the same URL, viewport, browser mode, and application state while comparing runs.
For pages where content loads after navigation, make the readiness condition specific: for example, a visible results container or a known message that appears after data arrives. Waiting for a generic document state alone may not represent application readiness.
Or skip the browser setup
ScreenshotNeo provides a screenshot API and MCP server for developers. One GET request can return a PNG, JPEG, WebP, or PDF. The same API call is useful when you need an image without managing Selenium, a browser binary, and a driver in your own capture script.
cURL
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}`);See the ScreenshotNeo API documentation for request options. Cookie banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
Create a free ScreenshotNeo account and start with 1,000 screenshots a month at no charge and no card required.
Performance, reliability, and cost notes
For a Selenium workflow, explicit waits make the capture condition clearer and avoid treating one arbitrary sleep as readiness. A viewport and browser/driver pairing that you record consistently make comparisons more useful. Screenshot reliability still depends on the site reaching the expected state in the current browser context; a successful PNG write alone does not validate the content.
For ScreenshotNeo, free usage is 1,000 shots per month with no card. Paid plans are Starter $5 for 3,000, 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. Every feature is on every plan. Only clean shots are billed, including no charge for bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits. See ScreenshotNeo for the product and plan details.
FAQ
Does a successful Selenium screenshot call mean the page loaded correctly?
No. It means WebDriver returned image data for the current browsing context. Verify the expected content separately.
Is headless Chrome inherently responsible for a white image?
The reviewed official sources do not establish a universal headless-mode defect. Compare the same page and state in visible and headless runs, with a known viewport.
Should I add a longer fixed sleep?
Usually, wait for a meaningful page-specific condition. A fixed delay can be too short on one run and unnecessarily long on another.
What should I include in a bug report?
Include the URL, page condition waited for, screenshot file, current URL and title, Selenium and browser/driver versions, operating system, headless mode, viewport, and relevant logs.
