Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
A Selenium TimeoutException in Docker is a symptom, not a diagnosis. First identify whether it occurs while creating a session, starting a Grid child container, navigating to a page, or waiting for an element. Then fix that layer: verify Selenium is ready, inspect the first browser error in the logs, provide adequate shared memory, align headless and Xvfb settings, and use a condition-specific wait for application state.
Identify which timeout you are seeing
The same exception name can describe failures at different stages. Increasing a timeout without locating the stage may only make a broken browser take longer to fail. Start with the stack trace and the last successful WebDriver command.
| Where it fails | Likely layer | First check |
|---|---|---|
| Session creation or driver-service startup | Browser process, Xvfb/headless configuration, shared memory, or browser/driver compatibility | Container logs and browser stderr |
| Dynamic Grid child container never becomes ready | Docker daemon connectivity or the child startup budget | Docker daemon reachability and --docker-server-start-timeout |
driver.get() or navigation |
Page-load behavior or target-site response | Page-load timeout and strategy |
wait.until(...) |
Application readiness, locator, or wait condition | Condition, locator, DOM, and screenshot |
| Intermittent failures during parallel runs | Host resource pressure, queueing, or too many sessions | CPU, memory, OOM events, and active session count |
Record the exact command that fails and the endpoint the client uses. A timeout during session creation is not fixed by changing an element wait, and a timeout inside wait.until() does not establish that the Selenium server failed to start.
Verify the Docker endpoint and wait for readiness
For traffic between containers on the same Docker network, use the Selenium container’s service or container name and its internal port. Use a published host port from the host, or from a client that is correctly routed to that host. A container showing as running does not prove that Selenium inside it is ready to accept sessions; Selenium’s Docker project explicitly warns that container startup and application readiness are different events.
#1 Best Overall
- Check the Grid UI or status endpoint from the same network location as the test client.
- Make sure the configured remote WebDriver URL matches that location: do not substitute
localhostinside one container when the server is another container. - Before creating a session, wait for a successful status response or implement a bounded retry with backoff in the harness. Stop retrying after a defined deadline and preserve the last response or connection error in the test log.
- Only begin the browser session after readiness succeeds. This separates server-start delays from failures during browser startup.
Selenium’s getting-started guidance recommends checking Grid status and describes Docker as a deployment approach. A readiness check is useful even if the same setup sometimes works without one: startup order and browser initialization can vary from run to run.
Read the first useful error in the container logs
The final TimeoutException is often downstream of the real fault. Follow logs while reproducing the error and look earlier for browser crashes, driver launch errors, missing display settings, failed image startup, or resource exhaustion.
docker logs -f seleniumFor more detailed Selenium server logging, set SE_OPTS to include --log-level FINE in the container environment, then restart and reproduce. For example, with a Compose service, add SE_OPTS: "--log-level FINE" under that service’s environment. Keep the verbose output long enough to capture the first browser or driver error before the timeout; reduce verbosity after diagnosis if the extra logs are too noisy for routine runs.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Give the browser enough shared memory
Browser processes in containers can fail or become unstable when shared memory is constrained. The docker-selenium project documents --shm-size="2g" as a known starting workaround for browser crashes. It is a baseline, not a universal sizing guarantee: adjust for browser count, page complexity, and actual workload.
Rank #2
docker run -d --name selenium
-p 4444:4444
--shm-size="2g"
selenium/standalone-chrome:<pinned-tag>Replace <pinned-tag> with an image tag you have selected and tested; do not rely on latest for a repeatable browser environment. When changing image versions, keep track of the browser and driver versions too. If the failure began after an image update, compare the old and new image configuration and logs rather than assuming the timeout value is the cause.
Align headless mode with Xvfb
One Docker-specific startup failure occurs when SE_START_XVFB=false is set but the browser is not actually launched headless. If you disable Xvfb, pass the browser’s supported headless argument. If your intended headed configuration—or a headless mode that relies on Xvfb in your chosen image—needs a virtual display, leave Xvfb enabled.
- Check the container environment for
SE_START_XVFB. - Check the actual Chrome or Firefox launch arguments; do not infer headless mode from the fact that the test runs in Docker.
- Compare the first browser startup message in the logs with the selected display and headless settings.
- Change one setting at a time and retry session creation before adjusting unrelated client waits.
The official docker-selenium troubleshooting guidance connects the driver-service timeout and Chrome startup errors with this headless/Xvfb mismatch. If the browser exits immediately, increasing the Grid startup budget will not make the configuration valid.
Windows 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 reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteAdjust the Grid startup timeout only for slow legitimate startup
Selenium Grid’s Docker mode provides --docker-server-start-timeout, the maximum time it waits for a browser server in a child container to start before cancellation. Its documented default is 55 seconds. Raise it only after logs show that startup is progressing and image pulls or browser initialization sometimes exceed that budget.
--docker-server-start-timeout 90Use the option with the Grid command that starts your Docker-backed node, and choose a value based on observed startup duration and the time your job can tolerate. If the child container cannot reach the Docker daemon, has invalid Docker socket or URL configuration, or the browser crashes immediately, a larger timeout only delays the same failure.
The older standalone server also has separate timeout and browserTimeout controls. They concern reclaiming sessions after a disconnected client and limiting a hung browser, respectively. Treat them as server session controls, not substitutes for client-side synchronization or Grid child startup configuration.
Use explicit waits for application state
If the server and browser session are healthy but an element wait expires, wait for the specific state the next action needs. Selenium describes explicit waits as polling loops for a condition; the default WebDriverWait polling interval is 0.5 seconds. A wait raises TimeoutException if its condition never becomes true before the allotted time.
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
wait = WebDriverWait(driver, 20)
login = wait.until(
EC.visibility_of_element_located((By.ID, "login"))
)
login.click()Choose a condition that matches the next operation: visibility before reading or interacting with visible content, clickability before clicking, expected text before asserting text, a URL or title condition after navigation, or invisibility when waiting for a loading indicator to disappear. If the wait expires, inspect a screenshot and DOM from that exact run, then verify that the locator still matches the intended element.
A longer wait can be reasonable for a known slow operation, but adding blanket sleeps usually makes every run slower and still does not prove the application reached the required state. Selenium warns against mixing implicit and explicit waits because their combined timing can become unpredictable; a nominal 10-second implicit wait combined with a 15-second explicit wait can, for example, take about 20 seconds.
Separate navigation timeouts from element waits
If the exception occurs at driver.get(), inspect the page-load timeout and how navigation is expected to complete. Selenium’s page-load strategies determine when the navigation command returns:
normalwaits for the page’s load event.eagerreturns when the DOMContentLoaded event fires.nonereturns after the initial download without waiting for those events.
Choose the fastest strategy that still meets the test’s readiness requirements. A navigation strategy is not an application-state wait: after using a faster return condition, wait explicitly for the page element or state the test needs. If only one remote site times out, investigate that site’s response and client-side behavior instead of changing every Selenium wait globally.
Check Docker host capacity and concurrency
Selenium’s current documentation uses 1 CPU and 1 GB of RAM per browser as a starting sizing reference, not a fixed requirement. Actual needs vary with the browser, pages, and parallel load. When failures cluster under concurrency, reduce the number of simultaneous sessions temporarily. If the timeout rate changes, measure host CPU and memory use, CPU throttling, OOM kills, Docker daemon latency, and session queueing before changing timeouts.
- If a single session fails consistently, prioritize browser startup configuration, memory available to that container, and version compatibility.
- If failures appear only at higher parallelism, test lower concurrency first and add capacity or tune scheduling based on measured pressure.
- If a dynamic child container is slow but healthy, measure image-pull and browser startup duration before setting a longer startup budget.
Use this troubleshooting order
- Classify the failing command as session creation, Grid child startup, navigation, or element synchronization.
- Verify the client’s endpoint and confirm Selenium status from the client’s network location.
- Capture verbose container logs and locate the first browser or driver error.
- For startup failures, check shared memory, headless/Xvfb alignment, and browser/driver versions.
- For slow but progressing Grid startup, adjust the Docker server startup budget only after measuring it.
- For navigation or element failures, change the corresponding page-load strategy or explicit wait condition rather than a server timeout.
- For intermittent parallel failures, reduce concurrency and inspect host resource pressure.
Or skip the browser setup
If your goal is to capture a page screenshot rather than run browser interactions or Selenium assertions, ScreenshotNeo provides a website screenshot API and MCP server. One GET request can return an image or PDF; its clean-shot options handle cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, and cache hits are not billed, and an MCP server lets AI agents use screenshot tools.
For a PNG capture with cURL, the complete request is:
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-o shot.pngSee the ScreenshotNeo API documentation for request options and response details. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. This is for screenshot capture, not a replacement for Selenium when a test needs to click through an application or verify interactive behavior. Sign up for 1,000 free screenshots a month with no card.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →FAQ
Does a longer timeout fix every Selenium Docker TimeoutException?
No. It only helps when the failing operation is genuinely progressing but needs more time. It will not fix a browser that exits immediately, an unreachable Docker daemon, an incorrect locator, or an element condition that never becomes true.
What should I include in a useful timeout bug report?
Include the failing WebDriver command, full exception and stack trace, Selenium endpoint, image tag, browser and driver versions, relevant container environment settings, and the log lines preceding the timeout. For intermittent cases, note concurrency and whether reducing simultaneous sessions changes the outcome.
Frequently Asked Questions
Does a longer timeout fix every Selenium Docker TimeoutException?
No. It only helps when the failing operation is genuinely progressing but needs more time. It will not fix a browser that exits immediately, an unreachable Docker daemon, an incorrect locator, or an element condition that never becomes true.
What should I include in a useful timeout bug report?
Include the failing WebDriver command, full exception and stack trace, Selenium endpoint, image tag, browser and driver versions, relevant container environment settings, and the log lines preceding the timeout. For intermittent cases, note concurrency and whether reducing simultaneous sessions changes the outcome.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →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.
