How to Fix Selenium IDE Screenshot Save Failures

Start by identifying which workflow is failing. Selenium IDE saves projects and exported files through the browser’s download system because an extension cannot directly access your file system. Selenium WebDriver screenshot methods are separate: they return image data or write a PNG to a path supplied by your code. A download dialog, an IDE project-save problem, and a WebDriver path error require different fixes.

Use this order:

Confirm whether you are saving a Selenium IDE project/download or a screenshot created by WebDriver code.
Record the exact IDE, browser, operating-system, and runner versions.
Check where the browser or runner actually writes the file.
Verify the destination directory exists and is writable.
Run a minimal save test and inspect its return value or error.

1. Identify the failing save path

What you see	Likely path	First check
Selenium IDE repeatedly asks where to save	Browser download or extension save flow	Download settings, permissions, and the selected folder
The IDE project is not present after saving	Project export/download	Browser download history and actual download directory
Your test captures but no image appears	WebDriver screenshot API	Absolute path, directory existence, and the API result
The run freezes after a download	Browser/IDE download interaction	Minimal reproduction with the same browser and IDE versions

The Selenium IDE FAQ explains that the extension lacks direct file-system access, so save operations use browser downloads. See the official Selenium IDE FAQ. WebDriver screenshot behavior is documented separately in Selenium’s screenshots documentation and binding API references.

2. Fix Selenium IDE project and download saves

Check the browser download flow

Open the browser’s download history and locate the exported project or image. The file may have been saved to the default Downloads folder rather than the directory you expected.
Review the browser setting that asks for a location before each download. Repeated Save As dialogs can be normal when this setting is enabled.
Choose a directory where your account has write permission. Avoid protected operating-system folders.
Check whether the browser blocked the download, renamed it because a file already exists, or left it incomplete.
Run the export again with extensions that manage downloads disabled temporarily, if your organization allows that test.

Do not confuse project save with screenshot capture

A Selenium IDE project file contains commands and settings. It is not the same output as a screenshot generated by a WebDriver binding or an IDE command. If the project downloads correctly but an image is missing, debug the command and its output path separately.

Chrome integration workaround documented by the FAQ

The Selenium IDE FAQ describes a Chrome integration case where an external integration must answer the IDE project emit message; its example responds with undefined. That page was updated June 3, 2019, so treat this as a version-specific clue. Confirm your current Selenium IDE and Chrome versions before applying it as a general fix.

3. Save screenshots with WebDriver

WebDriver bindings can save a screenshot directly to a filename. Use an absolute path, create the directory first, and check the method’s result. The Python API documents a false result for an I/O error.

Python: complete minimal example

from pathlib import Path
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

output = Path("/tmp/selenium-shots")
output.mkdir(parents=True, exist_ok=True)

options = Options()
options.add_argument("--headless=new")
driver = webdriver.Chrome(options=options)
try:
    driver.get("https://example.com")
    target = output / "example.png"
    ok = driver.save_screenshot(str(target))
    if not ok:
        raise OSError(f"WebDriver could not write {target}")
    if not target.is_file() or target.stat().st_size == 0:
        raise OSError(f"Screenshot was empty or missing: {target}")
    print(target.resolve())
finally:
    driver.quit()

JavaScript: verify the file write

const { Builder } = require('selenium-webdriver');
const fs = require('node:fs/promises');

(async () => {
  const driver = await new Builder().forBrowser('chrome').build();
  try {
    await driver.get('https://example.com');
    const data = await driver.takeScreenshot();
    await fs.mkdir('/tmp/selenium-shots', { recursive: true });
    await fs.writeFile('/tmp/selenium-shots/example.png', data, 'base64');
  } finally {
    await driver.quit();
  }
})();

Path and permission checklist

Use a full path, not a path relative to an unknown runner working directory.
Create parent directories before calling the screenshot method.
Confirm the test process user can write there.
Check the boolean or promise result instead of assuming success.
Print the resolved path and file size in CI logs.
Use a unique filename when parallel tests run.

4. Diagnose common errors

Symptom	Cause	Fix
Save As opens every time	Browser download preference or extension file-system limitation	Inspect download settings and the actual download folder; select a writable directory.
No file, no error	Relative path resolved from an unexpected working directory	Switch to an absolute path and log it.
`save_screenshot` returns false	I/O failure	Create the directory, verify permissions, and check disk space.
File exists but is zero bytes	Incomplete write or interrupted run	Wait for the call to finish, then verify size before publishing the artifact.
Screenshot is blank	Page has not finished rendering or navigation failed	Wait for a reliable page condition, capture after navigation completes, and save browser logs.
Run freezes after a download	Version-specific browser/IDE download interaction	Reproduce with one project, one download, and recorded versions; compare another supported browser.
Project save works but image save fails	Different mechanisms are being debugged together	Test the IDE download and WebDriver screenshot independently.

Issue reports about repeated project-save dialogs and download freezes are useful clues, but they describe particular versions and environments. Do not treat them as proof that all Selenium IDE screenshot capture is broken.

5. Build a minimal reproduction

Record Selenium IDE version, browser version, operating system, WebDriver binding version, and runner.
Write down the exact command or API call and the expected destination.
Run one page and one screenshot with no project variables, downloads, or parallel workers.
Capture the browser download history or the WebDriver return value.
Record the resulting path, file size, console output, and any runner exception.
Compare the smallest Selenium IDE save case with the smallest WebDriver file-write case.

This split tells you whether the browser extension/download path or the API/file-write path is responsible.

6. Performance, reliability, and cost considerations

Use one screenshot call per required artifact and avoid repeated retries that overwrite the same file.
In CI, write to a workspace directory and upload artifacts after the browser closes.
Use unique names containing the test or build identifier when workers run concurrently.
Keep a small diagnostic log: URL, resolved path, return value, byte size, and elapsed time.
There is no published failure-rate statistic for Selenium IDE screenshot saves; measure your own environment instead of assuming a prevalence.
Browser downloads and local file writes consume your runner’s disk and time. An API can move capture and storage outside the test host.

7. Or skip the browser setup

ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF. Its capture flow accepts cookie and consent banners, removes more than 60 known consent platforms, newsletter popups, and chat widgets, and lets you turn each step off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers report the page verdict and billing status.

See the ScreenshotNeo API documentation for all options, including full-page and CSS-selector captures, device presets, custom viewports, dark mode, retina scale, waits, custom headers and cookies, blocking rules, JavaScript, PDFs, caching, signed links, asynchronous jobs, bulk capture, and usage reporting.

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)
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}`);

An MCP server also lets Claude, Cursor, and other MCP clients use take_screenshot, get_page_info, and capture_pdf. Plans include 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

8. FAQ

Why does Selenium IDE ask me where to save every time?

The extension uses the browser download flow because it cannot directly access the file system. Check the browser’s download preference and destination.

Should I debug Selenium IDE or WebDriver first?

Debug the path that produced the symptom. IDE project/download saves and WebDriver screenshot calls are separate mechanisms.

What does a false screenshot result mean in Python?

It indicates an I/O error. Check the full path, parent directory, permissions, and disk space.

Are old Selenium IDE issue reports universal fixes?

No. Reports are tied to specific versions and sequences. Use them as clues and reproduce the smallest failing case.

Can I avoid local browser file handling?

Yes. ScreenshotNeo returns the capture from an API request and can also run through its MCP server for AI-agent workflows.