Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallSome links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
First find out whether Selenium fails to start the browser, send the JavaScript command, or return its result. These are different failure layers: a missing driver or failed Chrome launch means the script never ran, while a timeout, wrong frame, or browser-side exception points toward the command or page context. Capture the full exception and versions before changing code; the title alone does not identify one confirmed root cause.
Identify which stage is failing
A Selenium JavaScript failure in Docker is not necessarily a JavaScript bug. A WebDriver command can only execute after a browser session exists, and the script runs in the currently selected window and frame. Start by recording the exact exception, stack trace, and failing line, then classify it:
- Session creation fails: Investigate browser startup, driver discovery, browser-driver compatibility, container resources, and logs. The JavaScript was not reached.
- The synchronous probe works but your script fails: Check the script itself, selected frame or window, argument and return types, and browser console errors.
- An asynchronous script hangs or times out: Check that its completion callback is called and that the script timeout is suitable.
- Only startup-time commands fail intermittently: Check service readiness and resource availability instead of assuming that a running container is ready to accept WebDriver commands.
Record Java, Selenium, Chrome, ChromeDriver, Docker image tag, and container architecture. Also note whether the same operation succeeds outside Docker. These details help distinguish a repeatable compatibility or code problem from container-specific startup behavior.
Separate browser startup from JavaScript execution
If new ChromeDriver() or creation of a remote session fails, first make the browser session work. Selenium’s driver installation guidance discusses driver-location errors when an executable is unavailable, and its Chrome guidance says Chrome and ChromeDriver versions should match. Check that the required driver is available to Selenium inside the container and verify the versions used by the exact image you run: Selenium driver installation and Chrome-specific WebDriver guidance.
#1 Best Overall
Once a session exists, try a small synchronous probe. It checks whether Selenium can issue a script command and receive a basic result; it is a diagnostic step, not proof that an application-specific script is correct.
Object state = ((JavascriptExecutor) driver).executeScript("return document.readyState");
System.out.println(state);If this succeeds, focus on the application script and its context. Selenium executes JavaScript in the currently selected frame or window. Confirm that the test has switched into the intended frame and window before executing the script, and check whether the arguments and return value use types supported by the Java API. See the JavascriptExecutor API reference.
Use the executor that matches the script
Synchronous work: executeScript
Use executeScript for JavaScript that can return immediately. Its result comes back as the result of the script; it is not a mechanism for waiting on a browser operation that will finish later. Start with the smallest useful snippet, then add the page-specific logic once the probe succeeds.
Recommended Free Tools
Asynchronous work: callback plus a script timeout
Use executeAsyncScript when the script completes later. Selenium provides a completion callback as the final entry in the script’s arguments; call it with the result when the asynchronous operation finishes. The Java API documents a zero-millisecond default for the asynchronous script timeout, so set an explicit workload-appropriate timeout before running longer work.
import java.time.Duration;
import org.openqa.selenium.JavascriptExecutor;
import org.openqa.selenium.WebDriver;
// Assumes driver is an active WebDriver session.
driver.manage().timeouts().scriptTimeout(Duration.ofSeconds(30));
Object result = ((JavascriptExecutor) driver).executeAsyncScript(
"const done = arguments[arguments.length - 1];" +
"window.setTimeout(() => done('finished'), 500);"
);
System.out.println(result);The 30-second value is an example, not a universal recommendation; choose a limit appropriate to the operation and test. If the callback is never invoked, the script cannot complete normally. If it returns a value different from what you expect, check Selenium’s documented serialization behavior. For API details, see WebDriver.Timeouts and JavascriptExecutor.
Check page context and browser-side errors
A script that works in one frame may fail in another. Verify the selected window and frame at the point of execution, rather than assuming Selenium is still in the context used by an earlier step. If the code accesses another frame or makes a cross-domain request, inspect the browser console and consider browser security restrictions. Docker can expose or aggravate a setup problem, but it does not remove browser security rules.
Stabilize Chrome and Selenium inside Docker
Allocate shared memory based on the workload
The maintained docker-selenium project documents --shm-size=2g as an arbitrary, commonly working workaround for browser crashes, and explicitly notes that actual needs vary. For example, when running a Selenium container directly, you can test with:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsdocker run --shm-size=2g selenium/standalone-chrome:<full-image-tag>Replace the tag with the complete image tag you intend to use. The example is not a claim that every workload requires exactly 2 GB or that this command alone configures every deployment. If you use Compose, Grid, or another container arrangement, apply the shared-memory setting in the corresponding service configuration and consult that image’s documentation.
Rank #3
Pin the image and verify browser compatibility
Use a complete image tag to make the Selenium, browser, and driver combination reproducible. An unpinned latest tag can move, making a previously stable combination change between runs. Record the exact tag alongside the browser and driver versions; verify Chrome/ChromeDriver compatibility using Selenium’s current Chrome guidance rather than relying on a version combination remembered from another image.
Check headless and Xvfb configuration for the exact image
Headless Chrome or Chromium behavior can depend on both browser version and image configuration. The docker-selenium project describes changes around Chrome/Chromium 127 and 132 and provides version-specific guidance for SE_START_XVFB. Verify the current project instructions against the exact browser and image tag you run; do not assume one Xvfb setting applies to all versions.
Wait for the service, then inspect logs
A container process being up does not establish that Selenium Grid is ready to receive commands. Poll its status or health check, or otherwise wait for readiness before creating a session or issuing commands. If startup or browser execution fails, inspect docker logs <container>. The docker-selenium project sends container output to stdout and documents increasing Selenium log verbosity with SE_OPTS; use the logs to identify whether Chrome failed to launch, the driver could not be found, or the service was not ready.
Do not add Chrome flags by reflex
Options such as --no-sandbox may be relevant in some container deployments, and Selenium includes the option in Chrome configuration examples. That does not make it a universal fix. Inspect the actual Chrome launch error and the image guidance first; adding unrelated flags can obscure the cause instead of resolving it. See Selenium’s Chrome documentation.
Use the symptom to choose the next check
| Symptom | First branch to investigate | Next evidence-based step |
|---|---|---|
| Browser or session creation fails | Container startup, driver discovery, browser-driver compatibility | Confirm the driver is available, check Chrome/ChromeDriver compatibility, and inspect startup logs. Driver guidance; Chrome guidance. |
| Browser exits or crashes in Docker | Container and browser stability | Check shared-memory allocation and exact image/browser versions, then inspect container logs. docker-selenium guidance. |
| The synchronous probe works but the application script fails | Script body, frame/window, arguments, or browser console | Verify context and supported argument types; inspect browser-side errors. JavascriptExecutor API. |
| An asynchronous call hangs or times out | Completion callback and script timeout | Ensure the callback is invoked and configure a suitable Java script timeout. Timeout API. |
| Failures appear intermittently near startup | Service readiness and available resources | Wait for Grid readiness and review logs; a running container alone is not evidence of readiness. docker-selenium project. |
Or skip the browser setup
If your actual goal is to capture a website screenshot rather than run browser-side JavaScript, ScreenshotNeo provides a one-request screenshot API and an MCP server. A request can return PNG, JPEG, WebP, or PDF. Its clean-shot steps can accept consent banners and remove known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP tools include take_screenshot, get_page_info, and capture_pdf, for Claude, Cursor, and other MCP clients.
For a one-call WebP capture, adapt the target URL as needed:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. ScreenshotNeo is worth considering when you need clean website captures rather than a Selenium test session. Sign up for 1,000 free screenshots a month with no card.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Troubleshooting checklist
- Save the full error. Record the exception, stack trace, failing line, and whether session creation succeeded.
- Record the environment. Capture Java, Selenium, Chrome, ChromeDriver, image tag, and architecture so the failing combination can be reproduced.
- Prove the session works. Run the
document.readyStateprobe. If it fails before returning, stay on the startup or command path rather than rewriting the application script. - Prove the execution context. Confirm the current window and frame and simplify the script to a minimal return value.
- Match sync/async behavior. Use
executeScriptfor immediate results; for async work invoke Selenium’s callback and set an explicit script timeout. - Check container conditions. Verify the full image tag, browser/driver compatibility, shared memory, headless/Xvfb guidance, service readiness, and logs.
- Change one variable at a time. After each change, rerun the same minimal reproduction. This makes it possible to tell whether a fix addressed startup, execution, or result handling.
Common causes and fixes
Driver executable is unavailable
Clue: Driver-location or session-creation error before the script line. Fix: Confirm the driver is present and discoverable inside the container, then verify the browser and driver versions.
Browser and driver do not match
Clue: Chrome fails during session startup or reports a compatibility problem. Fix: Check the exact Chrome/ChromeDriver pair and pin the full Selenium image tag so the combination does not change unexpectedly.
Insufficient shared memory or browser crash
Clue: Browser exits or crashes within the container. Fix: Check the shared-memory configuration and container logs. The docker-selenium project gives --shm-size=2g as an arbitrary known workaround, not a universal requirement.
Grid receives commands before it is ready
Clue: Startup failures are intermittent and occur before a stable session. Fix: Wait for the service’s readiness/status rather than relying on the container’s running state.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Async callback is omitted
Clue: executeAsyncScript never returns normally. Fix: Call the final arguments callback on every completion path and set an appropriate script timeout.
Script runs in the wrong frame or window
Clue: A basic script works but application-specific DOM access fails or sees the wrong page. Fix: Select the intended window and frame before execution, then inspect browser console errors and cross-origin restrictions.
Frequently Asked Questions
Does a JavaScript execution error prove that Docker is the cause?
No. Session startup, WebDriver command delivery, script behavior, and browser policy are separate failure layers. The exception and the stage at which it occurs determine which one to investigate.
Can I use ScreenshotNeo instead of Selenium for browser automation tests?
No. ScreenshotNeo is a screenshot API and MCP server, not a replacement for Selenium’s WebDriver test-session behavior. It fits website screenshot capture, not arbitrary browser automation.
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.
