How to Fix Selenium Screenshots Failing with Chrome Sandbox Errors

If Chrome refuses to start and its error identifies the sandbox, add --no-sandbox to the Chrome options for the affected Selenium session, then rerun a minimal reproduction. This is a targeted workaround for a Chrome launch failure; it will not fix every screenshot error. If the browser starts and navigation works but the screenshot command fails, diagnose that separately.

Disabling Chrome’s sandbox weakens a browser isolation boundary. Use the flag only when the automation environment requires it, and prefer configuring the runtime so Chrome’s normal sandbox can operate when feasible. Do not use this configuration for untrusted browsing workloads.

1. Confirm where the failure occurs

Reduce the script to three steps: create the Chrome session, navigate to one page, and take one screenshot. Save the full exception and determine whether Chrome exits during session creation or stays running until the screenshot call.

• Session creation fails with a sandbox-related Chrome message: try the Chrome option below.
• Session starts and navigation succeeds, but the screenshot call throws: investigate the screenshot exception, ChromeDriver logs, and browser and driver versions. Do not keep adding sandbox flags without evidence.
• The failure happens only on a remote node or in CI: check that the option reaches the Chrome process on that node and separate sandbox configuration from display or headless configuration.

Record the Selenium, Chrome, and ChromeDriver versions, operating system or container details, exact launch arguments, and whether Chrome starts. Selenium notes that many reported errors originate in the underlying drivers that receive its commands, so the complete exception and driver logs matter.

2. Fix a Chrome sandbox launch error in Python

Add the argument to the ChromeOptions passed to the driver. Keep the navigation and screenshot steps simple while confirming the fix:

from selenium import webdriver

options = webdriver.ChromeOptions()
options.add_argument("--no-sandbox")

driver = webdriver.Chrome(options=options)
try:
    driver.get("https://example.com")
    driver.save_screenshot("screenshot.png")
finally:
    driver.quit()

This changes the Chrome process arguments for this WebDriver session. It does not change Selenium’s screenshot API, and it is not a general remedy for errors after Chrome has started.

3. Configure headless mode separately

Headless mode controls whether Chrome displays a browser window. It does not disable the sandbox and should not be treated as a sandbox fix. If the CI machine has no display, add the headless argument separately:

from selenium import webdriver

options = webdriver.ChromeOptions()
options.add_argument("--no-sandbox")  # Only when required by the environment
options.add_argument("--headless=new")  # Separate display-mode setting

driver = webdriver.Chrome(options=options)
try:
    driver.get("https://example.com")
    driver.save_screenshot("screenshot.png")
finally:
    driver.quit()

Use the headless argument supported by the installed Chrome version. Chromium’s testing guidance also describes --ozone-platform=headless for tests that do not need to draw; tests that need a display can run under Xvfb. Choose based on the execution environment and what the test requires.

4. Pass Chrome options to a remote WebDriver session

With Selenium Grid or another remote WebDriver endpoint, Chrome runs on the remote node. Put --no-sandbox in the Chrome options used to create that remote session so the option reaches the browser process:

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

options = Options()
options.add_argument("--no-sandbox")

# Replace this endpoint with your configured remote WebDriver URL.
driver = webdriver.Remote(
    command_executor="http://localhost:4444",
    options=options,
)
try:
    driver.get("https://example.com")
    driver.save_screenshot("remote-screenshot.png")
finally:
    driver.quit()

If local Chrome works but the remote session still fails, inspect the remote node’s Chrome startup logs and confirm its capabilities include the argument. Changing options in the client process cannot repair a Chrome process that never receives them.

5. Check Chrome and ChromeDriver versions

Capture the actual browser and driver versions from the environment where Chrome runs. Selenium’s Chrome guidance says the Chrome and ChromeDriver major versions must match. Its current Chrome documentation describes Selenium 4 as compatible with Chrome v75 and newer; that does not guarantee every browser and driver combination works.

When the major versions differ, align ChromeDriver with the installed Chrome major version, or update the browser and driver together using the version management approach appropriate to your environment. Re-run the minimal reproduction after changing versions so you can distinguish a compatibility problem from a sandbox launch problem.

6. cURL, Python, and Node.js alternatives

Selenium’s Chrome options are language bindings over the same browser configuration. The equivalent Chrome argument is --no-sandbox; use it only for the affected session and only when required.

Python

from selenium import webdriver

options = webdriver.ChromeOptions()
options.add_argument("--no-sandbox")
driver = webdriver.Chrome(options=options)
try:
    driver.get("https://example.com")
    driver.save_screenshot("screenshot.png")
finally:
    driver.quit()

Node.js

const { Builder } = require('selenium-webdriver');
const chrome = require('selenium-webdriver/chrome');

(async () => {
  const options = new chrome.Options().addArguments('--no-sandbox');
  const driver = await new Builder()
    .forBrowser('chrome')
    .setChromeOptions(options)
    .build();

  try {
    await driver.get('https://example.com');
    const png = await driver.takeScreenshot();
    require('fs').writeFileSync('screenshot.png', Buffer.from(png, 'base64'));
  } finally {
    await driver.quit();
  }
})();

Run the Node.js example in a project with Selenium WebDriver and ChromeDriver available, and use a compatible installed Chrome/ChromeDriver pair.

cURL

cURL does not launch Chrome or create a Selenium WebDriver session, so it cannot pass Chrome launch flags or repair a Selenium sandbox error. It can call a screenshot service that runs the browser remotely. For example, ScreenshotNeo provides an HTTP screenshot API; its code example appears below.

7. Troubleshooting common errors

Symptom	Likely cause	What to do
Chrome exits during session creation with a sandbox error	The runtime cannot start Chrome with its current sandbox setup.	Add --no-sandbox to the affected session’s Chrome options, then retry the minimal case. Treat it as a constrained workaround.
Chrome starts, but save_screenshot or takeScreenshot fails	The failure may be in the driver command, session, page state, or capture call rather than sandbox startup.	Keep the full exception, inspect ChromeDriver/Selenium logs, and check whether other WebDriver commands still work. If possible, reproduce in another browser to help isolate a driver-specific issue.
Local works, remote fails	The option may not have reached Chrome on the Grid or remote node.	Set the Chrome option in the capabilities used to create the remote session and inspect the remote browser logs.
Failure mentions missing display or window system	The environment may lack a display; this is separate from sandboxing.	Use a supported headless mode for the installed Chrome, or use Xvfb when the test needs a display.
ChromeDriver reports a session or startup failure after an update	Chrome and ChromeDriver may have incompatible major versions.	Read both actual versions and align their major versions.
Adding --headless=new does not fix the sandbox error	Headless mode selects display behavior; it does not disable Chrome’s sandbox.	Diagnose sandbox startup separately and add the targeted sandbox option only if the launch error supports it.
Adding --no-sandbox makes no difference	The original diagnosis may be wrong, or the option may not be applied to the failing Chrome process.	Check the exact exception, effective Chrome arguments, remote/local execution location, and browser/driver logs.

8. Performance, reliability, and cost

--no-sandbox is a launch configuration, not a screenshot speed setting. The cited Selenium and Chromium guidance does not establish a performance gain from adding it. Headless execution, page loading, network conditions, and page behavior can affect capture time, so measure those in the environment that runs the job rather than assuming the sandbox flag improves performance.

For reliability, make the automation report session creation, navigation, and screenshot capture as distinct steps. Preserve logs and version details when a failure occurs, and verify remote capabilities at the browser node. A successful browser launch does not prove the later screenshot command will succeed.

For cost, this fix requires configuration and version diagnosis; the research sources do not establish a need to buy hardware, software, or troubleshooting tools. If maintaining browser and driver setup is the obstacle, a hosted screenshot API is another approach.

9. Or skip the browser setup

For a hosted capture, ScreenshotNeo takes a URL in one API request and returns an image or PDF. See the ScreenshotNeo API documentation.

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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', image);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. ScreenshotNeo is a website screenshot API and MCP server by Yorker Media.

Sign up for 1,000 free screenshots a month with no card.

10. FAQ

Does --no-sandbox fix every Selenium screenshot error?

No. It targets Chrome launch failures that identify the sandbox. A failure in the screenshot command after a successful launch needs its own diagnosis.

Should I always disable the sandbox in CI?

No. Use it only when required by the constrained runtime, because it weakens Chrome’s isolation boundary. Configure the environment to support the normal sandbox when feasible.

Does headless Chrome mean sandboxing is disabled?

No. Headless mode and sandbox configuration control different aspects of Chrome execution.

What information should I include when asking for help?

Provide the complete exception, Selenium/Chrome/ChromeDriver versions, operating system or container details, launch arguments, whether the browser starts, and whether the failure occurs locally or remotely.