A Selenium timeout is not one problem or one setting. First identify the operation that exceeded its deadline: browser navigation, element synchronization, asynchronous JavaScript, or a remote client/Grid/network hop. Then change the timeout owned by that layer and verify the slower component instead of increasing every value.
This guide shows how to classify the exception, configure Selenium 4 timeouts in Java and Python, choose a page-load strategy, synchronize dynamic pages, and diagnose Grid and CI failures.
Identify which timeout actually failed
Capture the complete exception, stack trace, command, URL, session location, and elapsed time. The operation named in the trace usually points to the owner of the deadline.
| Symptom or operation | Timeout category | Inspect first |
|---|---|---|
driver.get() or navigation does not return before its deadline |
WebDriver page-load timeout | Page-load strategy, redirects, blocking resources, endpoint performance, and whether full load is required |
| Element lookup fails before the element exists | Implicit wait or an explicit wait around a condition | Locator and application state; prefer a condition-based explicit wait |
A WebDriverWait condition is never satisfied |
Explicit-wait timeout | Whether the condition is correct, the UI reached that state, and the app returned an error |
executeAsyncScript (Java) or execute_async_script (Python) does not call back |
Script timeout | Callback completion and the session’s script-timeout value |
| Read timeout, connection reset, delayed session creation, or a command that never reaches the browser | Client transport, Grid, proxy/load balancer, CI, or framework deadline | Which component emitted the error and the deadline at every network hop |
Do not call all of these “the Selenium timeout.” A page-load timeout is a WebDriver session setting; an HTTP read timeout belongs to the client or an intermediary; and a Grid allocation deadline can occur before a browser command is sent.
Know Selenium’s separate timeout settings
The Selenium Project’s current browser-options documentation lists new-session defaults of 300,000 milliseconds (5 minutes) for page load, 30,000 milliseconds for asynchronous scripts, and 0 milliseconds for implicit waits. These are WebDriver session defaults, documented for Selenium Project material current in 2026; they are not universal HTTP or Grid defaults and are not recommendations for every application. See Browser Options, the Java timeouts API, and the Python timeouts API.
| Setting | Controls | Does not control |
|---|---|---|
| Page-load timeout | How long navigation waits for the selected page-readiness point | Element appearance, async callbacks, or a proxy’s socket deadline |
| Script timeout | Completion of asynchronous JavaScript with a callback | Normal synchronous scripts or page navigation |
| Implicit wait | How long element-location calls may poll for a matching element | Navigation duration or arbitrary application work |
| Explicit wait | A condition you define, polled until true or its deadline | Other commands that are not inside that wait |
Set measured limits in Selenium 4
Java
Selenium 4 uses Duration rather than the older (long, TimeUnit) overload. The following creates a 45-second navigation budget, a 30-second asynchronous-script budget, and no implicit polling:
import java.time.Duration;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
WebDriver driver = new ChromeDriver();
driver.manage().timeouts().pageLoadTimeout(Duration.ofSeconds(45));
driver.manage().timeouts().scriptTimeout(Duration.ofSeconds(30));
driver.manage().timeouts().implicitlyWait(Duration.ZERO);
try {
driver.get("https://your-app.example/login");
} finally {
driver.quit();
}Choose 45 seconds only when it matches your application’s observed response distribution and suite budget. A larger number gives a slow operation more time; it does not fix a stalled server, browser driver, route, or proxy.
Python
from selenium import webdriver
options = webdriver.ChromeOptions()
driver = webdriver.Chrome(options=options)
driver.set_page_load_timeout(45)
driver.set_script_timeout(30)
driver.implicitly_wait(0)
try:
driver.get("https://your-app.example/login")
finally:
driver.quit()These setters take seconds in the Python binding. Confirm behavior against the Selenium version installed in your environment before standardizing a helper library.
Recommended Free Tools
Choose the page-load strategy deliberately
Page-load strategy determines the readiness point for navigation. It applies to the WebDriver session, so changing it changes synchronization requirements across tests.
| Strategy | Navigation returns when | What your test must still do |
|---|---|---|
normal |
The browser reaches the load event, including resources that block that event | Wait for application-specific state; load completion does not prove a single-page app finished rendering |
eager |
The DOMContentLoaded event fires | Explicitly wait for data, controls, or text populated after DOMContentLoaded |
none |
WebDriver does not block for page readiness | Provide explicit waits before every action that depends on the page |
For example, in Java:
import org.openqa.selenium.chrome.ChromeOptions;
ChromeOptions options = new ChromeOptions();
options.setPageLoadStrategy("eager");
WebDriver driver = new ChromeDriver(options);Use eager or none only when you can name the condition that proves the state under test is ready. document.readyState == "complete" is not proof that a single-page application’s asynchronous requests and component updates are finished.
Rank #3
Synchronize dynamic interfaces with explicit conditions
Selenium’s official Waiting Strategies documentation says, “Warning: Do not mix implicit and explicit waits.” An implicit wait changes the polling behavior of element-location calls inside explicit waits, making total duration difficult to predict. Keep the implicit wait at zero and use explicit waits for local, meaningful conditions.
Java condition example
import java.time.Duration;
import org.openqa.selenium.By;
import org.openqa.selenium.support.ui.ExpectedConditions;
import org.openqa.selenium.support.ui.WebDriverWait;
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(20));
driver.get("https://your-app.example/orders");
wait.until(ExpectedConditions.visibilityOfElementLocated(By.cssSelector("[data-testid='orders']")));
wait.until(ExpectedConditions.textToBePresentInElementLocated(
By.cssSelector("[data-testid='status']"), "Ready"));Python condition example
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)
driver.get("https://your-app.example/orders")
wait.until(EC.visibility_of_element_located((By.CSS_SELECTOR, "[data-testid='orders']")))
wait.until(EC.text_to_be_present_in_element(
(By.CSS_SELECTOR, "[data-testid='status']"), "Ready"))Wait for the state the next action needs: a visible control, expected text, a URL change, an enabled button, or a known completion marker. A fixed sleep can be too short on a slow run and waste time on a fast one. Selenium identifies poor synchronization as a common source of errors in its Troubleshooting Assistance documentation (last modified November 7, 2024).
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 reinstallOutdated 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 matchInvestigate server, browser, and network latency
- Replay the target endpoint outside Selenium with a normal HTTP client and record DNS, TLS, time-to-first-byte, redirects, and total time.
- Check application logs for slow database calls, upstream failures, queueing, or 5xx responses during the test timestamp.
- Enable Selenium and browser-driver logs and preserve the browser console and network trace when possible.
- Compare local and remote runs. A local pass and remote failure points toward routing, proxy policy, node capacity, or an outer deadline rather than a selector alone.
- In restricted environments, verify DNS, certificates, firewall rules, and proxy settings. Selenium’s options documentation describes proxy configuration for traffic capture, backend mocking, and complex corporate networks: Browser Options.
Separate a slow origin from a blocked resource: a page can appear stalled because an analytics, font, third-party API, or redirect never completes. If the test does not need that resource, blocking it in a controlled test profile can reduce variance, but document the changed behavior.
Rank #4
Diagnose remote WebDriver, Grid, and CI timeouts
Map every hop: test client → WebDriver endpoint or Grid → browser driver and browser → application, with any proxy/load balancer and CI or test-framework deadline around that path. A command can be healthy at the browser while an intermediary closes the connection first.
- Session creation waits: check Grid queue depth, node availability, capacity, and browser/driver compatibility.
- Command reaches a node but returns late: inspect node CPU, memory, container throttling, browser-driver logs, and the application route.
- Connection resets or client read timeouts: compare client, load-balancer, proxy, and CI deadlines; identify which layer emitted the message.
- Only parallel runs fail: reduce concurrency temporarily and check for saturated nodes, ephemeral-port exhaustion, or an application rate limit.
A SeleniumConf 2023 deployment presentation illustrates multiple interacting timeout layers, but its configuration values describe that deployment and are not current universal Grid or cloud defaults. Use the documentation for your Grid release and hosting provider for exact settings: Selenium Grid Deployment Alternatives.
Common timeout errors and targeted fixes
| Observed failure | Likely cause | Targeted fix |
|---|---|---|
TimeoutException from get() |
Navigation did not reach the strategy’s readiness point | Measure the endpoint, inspect redirects/resources, set a suitable page-load timeout, or use eager/none with explicit state waits |
| Explicit wait expires | Wrong locator, wrong expected state, JavaScript error, or backend failure | Capture DOM and console evidence; validate the condition and application response before extending the wait |
| Async script timeout | Callback never executes or a promise-like flow is not bridged to the callback | Guarantee callback completion on success and error paths; set script timeout to the measured operation budget |
| Element not found immediately | Implicit wait is zero and the UI is still changing | Use an explicit wait around the required condition, not a global navigation timeout |
| Remote read timeout or session creation timeout | Client, Grid, proxy, load balancer, or CI deadline is shorter than the command | Trace the request path and align deadlines; inspect queueing and node health instead of only increasing WebDriver values |
Make timeout handling reliable and economical
- Set one documented budget per operation type: navigation, async script, and explicit condition.
- Keep WebDriver’s budget at or below an appropriate outer client/CI deadline where possible; otherwise an outer layer may terminate the command first. This is an operational inference from the multiple layers, not a Selenium universal rule.
- Record URL, command, strategy, timeout values, browser/driver versions, Grid node, timestamps, and the originating exception.
- Retry only transient infrastructure failures with a small, bounded policy. Do not retry deterministic locator or application errors.
- Use a representative test page and monitor percentile latency over time rather than selecting an arbitrary 30-, 60-, or 120-second value.
Or skip the browser setup
If your goal is to obtain a clean website image for a report, artifact, or visual check rather than exercise browser interactions, ScreenshotNeo provides a one-request screenshot API and an MCP server for AI agents. 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, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minutecURL (see the full ScreenshotNeo documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
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}`);The MCP server exposes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. Every plan includes the features; 1,000 screenshots per month are free with no card, and paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
Frequently Asked Questions
Does increasing the page-load timeout also make element waits longer?
No. Page-load, implicit, explicit, and asynchronous-script timeouts are separate controls owned by different WebDriver operations.
What should I check when a test passes locally but times out on Grid?
Compare session-allocation time, node load, browser and driver versions, proxy route, command latency, and CI or load-balancer deadlines. The failing hop, not the largest timeout value, identifies the fix.
Is a successful navigation proof that a single-page app is ready?
No. Navigation can return at the load or DOMContentLoaded event while later API calls and JavaScript rendering continue. Wait for the application condition your next action requires.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →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.
