How to Fix Selenium Python’s “Unhandled Inspector Error” When Taking Screenshots

Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.

“Unhandled inspector error” is a wrapper, not a diagnosis. Read the complete inner message and identify the WebDriver operation that failed. If it says Cannot take screenshot with 0 width, wait for the target element to become visible and verify its dimensions. If it says Browser window not found, investigate a closed browser window, a lost session, or a Chrome/ChromeDriver environment problem—even when the exception appears near screenshot code.

Start with the complete exception

Selenium often reports an outer error such as unknown error: unhandled inspector error and places the useful diagnosis in the nested message. Log the whole exception, not only its first line:

#	Preview	Product	Price
1		Selenium with Python Simplified For Beginners - Simple, Concise & Easy guide to Automation Testing...	$10.99	Buy on Amazon
2		Test-Driven Development with Python: Obey the Testing Goat: Using Django, Selenium, and JavaScript	$55.21	Buy on Amazon
3		Test-Driven Development with Python: Obey the Testing Goat: Using Django, Selenium, and JavaScript	$42.00	Buy on Amazon
4		Automation Testing with Python & Selenium: Master Practical Skills for Real-World Automation (QA...	$17.99	Buy on Amazon
5		Developing Bots with Selenium Python: For Web Scraping, Test Engineering, Data Mining, and...	$21.95	Buy on Amazon

from selenium import webdriver

try:
    driver.save_screenshot("page.png")
except Exception as exc:
    print(repr(exc))
    print(str(exc))
    raise

Record the exact failing statement too. A screenshot call, element screenshot, navigation, maximize, or window-size command can each expose a different underlying problem. The two variants most often confused are zero-width element captures and missing browser windows.

Identify which failure you have

Do not apply an element-visibility fix to a dead browser session, and do not treat every screenshot exception as a screenshot bug.

#1 Best Overall

Sale

Selenium with Python Simplified For Beginners - Simple, Concise & Easy guide to Automation Testing using Python and Selenium WebDriver

$10.99

Buy on Amazon

Fix the zero-width element screenshot

Wait for visibility before capturing

An element can be present in the DOM while hidden, collapsed, covered, or not yet laid out. Selenium’s visibility wait checks that the element is displayed and has usable dimensions. Use the same locator you intend to capture:

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

options = webdriver.ChromeOptions()
# options.add_argument("--headless=new")  # enable only if you need headless mode
driver = webdriver.Chrome(options=options)
wait = WebDriverWait(driver, 20)

try:
    driver.get("https://example.com")
    target = wait.until(
        EC.visibility_of_element_located((By.CSS_SELECTOR, "main"))
    )
    target.screenshot("element.png")
finally:
    driver.quit()

WebElement.screenshot(path) writes an image file. WebElement.screenshot_as_png returns PNG bytes, which is useful when you want to process or upload the result yourself:

png_bytes = target.screenshot_as_png
with open("element.png", "wb") as image_file:
    image_file.write(png_bytes)

If the wait times out

• Check that the expected page actually loaded instead of redirecting to an error or login page.
• Verify the selector in browser developer tools. A typo or a frame-shadow-DOM boundary can make the expected element unreachable.
• Inspect whether a responsive breakpoint, modal state, CSS rule, or application transition keeps the element hidden.
• Confirm that the element is not inside an iframe. Switch to the correct frame before locating it.
• Print the element’s dimensions after the wait when debugging:

print(target.is_displayed(), target.size)
print(target.rect)

Visibility is a useful first check, not proof that every element is capturable. If its width remains zero, inspect the page state and layout rather than retrying blindly.

Capture the whole page instead

If you meant to capture the browser viewport rather than one element, use the driver method. Method names and capabilities vary by Selenium version, so check the API documentation for the version installed in your environment:

Rank #2

Sale

Test-Driven Development with Python: Obey the Testing Goat: Using Django, Selenium, and JavaScript

$55.21

Buy on Amazon

driver.save_screenshot("viewport.png")
# Equivalent byte-oriented form in Selenium versions that provide it:
# png_bytes = driver.get_screenshot_as_png()

Fix “Browser window not found”

Check whether Chrome exited

This message means ChromeDriver could not find the window associated with the session. The browser may have crashed or closed before the command. Test a simple navigation and inspect the window handles:

from selenium import webdriver

with webdriver.Chrome() as driver:
    print("handles at start:", driver.window_handles)
    driver.get("https://example.com")
    print("title:", driver.title)
    print("handles after navigation:", driver.window_handles)
    driver.save_screenshot("page.png")

If window_handles is empty, or navigation itself fails, fix the session before changing screenshot code. Do not call maximize_window() or set_window_size() until a stable window exists.

Separate window commands from capture

Reports have shown the same error during window sizing or maximizing, including cases where no screenshot command had run yet. Temporarily remove these calls to isolate the failing operation:

# Diagnose without window manipulation first
driver.get("https://example.com")
driver.save_screenshot("page.png")

# Add this only after the basic flow is stable:
# driver.set_window_size(1280, 900)
# driver.maximize_window()

For deterministic screenshots, setting a size is often preferable to maximizing, but it cannot repair a session whose browser has already disappeared.

Rank #3

Sale

Test-Driven Development with Python: Obey the Testing Goat: Using Django, Selenium, and JavaScript

$42.00

Buy on Amazon

Verify browser and driver pairing

Capture the versions used by the failing run:

import selenium
print("Selenium:", selenium.__version__)
print("Browser:", driver.capabilities.get("browserVersion"))
print("Driver:", driver.capabilities.get("chrome", {}).get("chromedriverVersion"))

Confirm that Chrome and ChromeDriver are compatible and that the executable being launched is the one you intended. A Selenium issue opened December 7, 2023 described Python 3.12, Selenium 4.16.0, and Chrome for Testing/ChromeDriver 120.0.6099.71 on Windows 11; the browser opened and then closed around set_window_size. The issue was closed as “not planned,” so it does not establish a universal fix.

A separate Chrome for Testing report compared CfT 119, 120, 121 beta, and 122 canary with a regular installed Chrome 120; the reporter saw the window error with the CfT builds but not the regular installation. Treat that as an environment-specific diagnostic comparison, not a support matrix or a recommendation to downgrade. Another Selenium report documented the message during maximize with Chrome 126.0.6478.127 and Selenium 4.22.0 on Windows.

Run a controlled comparison

1. Run the smallest script that starts Chrome, prints versions, navigates to a simple page, and takes one viewport screenshot.
2. Run it headed, then in your chosen headless mode, so you can see whether the process exits only in one mode.
3. Compare a regular installed Chrome with Chrome for Testing if your failure is specific to the latter.
4. Keep the same Python, Selenium, operating system, and driver while changing one variable at a time.

Do not assume that adding flags, changing headless mode, downgrading, or upgrading Selenium will fix every instance; the available reports do not prove a universal configuration change.

A diagnostic script that preserves useful evidence

import platform
import selenium
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

url = "https://example.com"
options = webdriver.ChromeOptions()
# options.add_argument("--headless=new")

driver = webdriver.Chrome(options=options)
try:
    print("Python platform:", platform.platform())
    print("Selenium:", selenium.__version__)
    print("Capabilities:", driver.capabilities)
    print("Initial handles:", driver.window_handles)

    driver.get(url)
    print("Current URL:", driver.current_url)
    print("Title:", driver.title)
    print("Handles after get:", driver.window_handles)

    target = WebDriverWait(driver, 20).until(
        EC.visibility_of_element_located((By.TAG_NAME, "body"))
    )
    print("Target size:", target.size)
    target.screenshot("element.png")
    driver.save_screenshot("viewport.png")
except Exception as exc:
    print("Full exception:", repr(exc))
    print("Current URL at failure:", getattr(driver, "current_url", "unavailable"))
    raise
finally:
    driver.quit()

Attach the complete output to a bug report or search query. Include Selenium and Python versions, browser and driver versions, operating system, headed/headless mode, the exact screenshot API, and the literal inner message.

Rank #4

Automation Testing with Python & Selenium: Master Practical Skills for Real-World Automation (QA Testing)

$17.99

Buy on Amazon

Or skip the browser setup

For a direct URL image or PDF, ScreenshotNeo provides a single HTTP request instead of maintaining a local Selenium session. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.

See the ScreenshotNeo documentation for all options. cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
const data = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', data));

Every plan includes the capture options, including full-page lazy-image loading, CSS-selector element capture, device presets and custom viewports, retina scale, PDF controls, custom CSS/JavaScript, clicks, waits, request blocking, headers and cookies, timezone/geolocation, transparent backgrounds, resizing, chosen-TTL caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage data, and an OpenAPI specification. Parameter names used by other screenshot APIs also work for easier migration.

The Free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free. Sign up for ScreenshotNeo and use the free allowance to test your pages.

Reliability, performance, and cost considerations

• Wait narrowly: wait for the selector or state that proves the page is ready instead of adding a large blind sleep.
• Use explicit dimensions: a fixed viewport makes local and CI captures more comparable than maximize.
• Reuse carefully: a long-lived driver can be faster, but discard and recreate a session after Chrome exits or the window handle disappears.
• Keep artifacts: save the HTML URL, capabilities, exception text, and a failure screenshot when one is available.
• Control dynamic pages: wait for network/application readiness and account for lazy images, animations, cookie dialogs, and authentication redirects.
• Do not hide failures: a retry cannot repair a zero-width hidden element or a missing browser process; classify the failure first.

Common errors and targeted fixes

What to include in a reproducible bug report

• Full exception, including the JSON message after unhandled inspector error.
• The exact failing line and whether it captures an element or the whole window.
• Python, Selenium, Chrome, and ChromeDriver versions.
• Operating system, headed/headless mode, and whether Chrome for Testing is used.
• Current URL, window handles, and the target element’s dimensions when applicable.
• A minimal script that removes unrelated waits, window commands, and application code.

FAQ

Is “unhandled inspector error” itself the root cause?

No. It is an outer WebDriver label. The nested message and failing operation determine the next diagnostic step.

Best Value

Developing Bots with Selenium Python: For Web Scraping, Test Engineering, Data Mining, and Automation (Mepso Media Bot Development Series)

$21.95

Buy on Amazon

Should I always switch to a regular Chrome installation?

No. A comparison can reveal an environment-specific difference, but the reported Chrome for Testing behavior is not a general support rule.

Can a screenshot error happen before screenshot code?

Yes. Reports show “Browser window not found” during maximize or window sizing, so inspect the complete command sequence.

What does Selenium return for an element screenshot?

screenshot_as_png provides PNG bytes, while screenshot(path) saves an element image; whole-window methods belong to the WebDriver object and vary by Selenium version.

Frequently Asked Questions

Is “unhandled inspector error” itself the root cause?

No. It is an outer WebDriver label. The nested message and failing operation determine the next diagnostic step.

Should I always switch to a regular Chrome installation?

No. A comparison can reveal an environment-specific difference, but the reported Chrome for Testing behavior is not a general support rule.

Can a screenshot error happen before screenshot code?

Yes. Reports show “Browser window not found” during maximize or window sizing, so inspect the complete command sequence.

What does Selenium return for an element screenshot?

screenshot_as_png provides PNG bytes, while screenshot(path) saves an element image; whole-window methods belong to the WebDriver object and vary by Selenium version.

Quick Recap

SaleBestseller No. 1

Selenium with Python Simplified For Beginners - Simple, Concise & Easy guide to Automation Testing using Python and Selenium WebDriver

$10.99

SaleBestseller No. 2

Test-Driven Development with Python: Obey the Testing Goat: Using Django, Selenium, and JavaScript

$55.21

SaleBestseller No. 3

Test-Driven Development with Python: Obey the Testing Goat: Using Django, Selenium, and JavaScript

$42.00

Bestseller No. 4

Automation Testing with Python & Selenium: Master Practical Skills for Real-World Automation (QA Testing)

$17.99

Bestseller No. 5

Developing Bots with Selenium Python: For Web Scraping, Test Engineering, Data Mining, and Automation (Mepso Media Bot Development Series)

$21.95

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.