Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
To increase Selenium’s connection timeout in Python, configure the HTTP client used by RemoteConnection. In current Selenium releases, create a ClientConfig with a timeout in seconds and pass a RemoteConnection built from it to webdriver.Remote. The older RemoteConnection.set_timeout(seconds) class method still appears in documentation but is deprecated in favor of client configuration.
This setting controls how long Selenium’s client waits for an HTTP response from the command executor (a local Selenium server, Grid, or hosted endpoint). It does not change element waits, page-load waits, asynchronous script waits, or WebDriverWait polling. Choosing the wrong timeout is the most common reason a larger number appears to have no effect.
Set the Selenium transport timeout with ClientConfig
Use this pattern when your Python process cannot establish or complete an HTTP request to the Selenium server quickly enough:
Recommended Free Tools
from selenium import webdriver
from selenium.webdriver.remote.remote_connection import RemoteConnection, ClientConfig
client_config = ClientConfig(
remote_server_addr="http://localhost:4444",
timeout=120, # seconds
)
connection = RemoteConnection(client_config=client_config)
driver = webdriver.Remote(
command_executor=connection,
options=webdriver.ChromeOptions(),
)
try:
driver.get("https://example.com")
finally:
driver.quit()The endpoint in the example is a local Selenium server. Replace it with the URL of your Grid or hosted provider. Constructor signatures have changed between Selenium Python versions, so check the API exposed by the version installed in your environment if this exact form raises a TypeError. The important pieces are the timeout value (in seconds), the remote-server address, and passing the configured connection as the command executor.
#1 Best Overall
Legacy form: RemoteConnection.set_timeout
Older code often contains:
from selenium.webdriver.remote.remote_connection import RemoteConnection
RemoteConnection.set_timeout(120)Selenium describes this method as “Override the default timeout,” but marks it deprecated. Treat it as a compatibility option for an older binding, not the preferred design for new code. Migrating to ClientConfig keeps transport settings attached to the connection object instead of changing a class-level default.
Know which Selenium timeout is failing
Selenium exposes several independent clocks. Match the exception and the operation to the setting before changing a value.
| Setting | Scope | Unit | Use it when | Typical symptom |
|---|---|---|---|---|
ClientConfig.timeout / remote-connection timeout |
HTTP transport between Python and the command executor | Seconds | The client cannot get a response from Selenium Server, Grid, or a hosted endpoint | Connection or request timeout while sending a command |
| Implicit wait | Element-location commands in a browser session | Seconds | You want element searches to keep polling for a limited period | An element lookup fails after the implicit period |
| Page-load timeout | Navigation commands such as driver.get() |
Seconds | A page does not finish loading within the allowed navigation time | Navigation raises a page-load timeout |
| Script timeout | Asynchronous JavaScript execution | Seconds | An async script does not call its completion callback promptly | Async JavaScript raises a script timeout |
WebDriverWait |
Polling a condition in your test code | Seconds | A condition should become true after commands are already being issued | The condition remains false until the explicit wait expires |
For example, if driver.find_element(...) cannot find an element, raising the HTTP connection timeout will not make the element appear. If navigation is slow, use the page-load timeout. If an asynchronous script runs too long, use the script timeout. WebDriverWait is a synchronization helper that polls a condition; it does not extend the underlying HTTP request timeout.
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 reinstallConfigure browser-session waits separately
Once the command executor is reachable, set browser-level limits on the driver when your failure belongs to a page, element, or script operation:
Rank #2
from selenium.webdriver.support.ui import WebDriverWait
# Browser navigation limit, in seconds
driver.set_page_load_timeout(90)
# Asynchronous JavaScript limit, in seconds
driver.set_script_timeout(60)
# Element searches (use only when a global implicit wait is appropriate)
driver.implicitly_wait(10)
# Condition polling after commands are returning
element = WebDriverWait(driver, 45, poll_frequency=0.5).until(
lambda d: d.find_element("css selector", "[data-ready='true']")
)These calls operate at the WebDriver/session level. Keep them conceptually separate from ClientConfig.timeout, which is applied by the HTTP client for requests sent to the command executor.
Choose a sensible connection-timeout value
The Selenium API does not publish a universal recommended number. Set a value that covers the normal round-trip time between your test process and the Selenium endpoint, including Grid scheduling and transient network latency, without allowing a dead endpoint to stall the suite indefinitely.
- Start with the smallest value that comfortably exceeds normal command latency in your environment.
- Use the same unit consistently: the Python APIs described here take seconds, not milliseconds.
- Increase the value only after checking the endpoint, proxy, TLS, and server health.
- Record the chosen value in configuration so local, CI, and hosted environments can use different limits without editing test logic.
A longer timeout changes how long the client waits; it does not make a server process faster, repair a broken route, or revive a failed browser node.
Diagnose a timeout that does not go away
1. Verify the command-executor URL
Confirm the scheme, host, port, and path supplied to remote_server_addr. A local server commonly listens on port 4444, while a Grid or hosted service may require a provider-specific path and authentication settings. Test from the same machine or container that runs Python; a URL reachable from your laptop may be inaccessible from CI.
2. Check proxy and TLS settings
Corporate proxies, firewall rules, and certificate validation can prevent the HTTP exchange from completing. RemoteConnection exposes transport options for proxy and certificate-related configuration. Correct those settings before simply increasing the timeout. A certificate or proxy rejection normally needs a configuration fix, not more waiting.
3. Inspect Selenium Server and Grid logs
Look for session-queue delays, unreachable nodes, browser-start failures, and process restarts at the same timestamp as the client exception. The client timeout only describes what the Python HTTP layer waited for; server and node logs explain why no response arrived.
4. Distinguish a transport timeout from a TimeoutException
The same broad word—timeout—appears in different Selenium errors. If the stack trace points to locating an element, navigation, or asynchronous JavaScript, adjust the corresponding WebDriver timeout. If a condition remains false after commands return, tune WebDriverWait and its polling interval. Change ClientConfig.timeout when the request to the command executor itself cannot complete.
5. Check browser-node health
A Grid node may be offline, overloaded, or unable to launch the requested browser. A larger client timeout can make the failure take longer to report, but it cannot repair the node. Confirm that the requested browser and driver are installed and that the node accepts new sessions.
Connection timeout versus page-load timeout in a real test
Consider a test that creates a remote session and then opens a slow application:
- The Python client sends the new-session command over the remote HTTP connection. If the server never responds, the
ClientConfig.timeoutgoverns how long that request waits. - After the session exists,
driver.get()sends a navigation command. The page-load timeout governs how long the browser waits for page-load completion. - After navigation returns,
WebDriverWaitcan poll for an application-specific condition, such as a data attribute or visible control.
Changing the transport timeout in step one does not extend steps two or three. Configure each layer deliberately rather than assigning one very large number to every wait.
Use a reusable connection factory
Keeping transport setup in one function makes it easier to select a different endpoint or timeout in CI:
import os
from selenium import webdriver
from selenium.webdriver.remote.remote_connection import RemoteConnection, ClientConfig
def make_driver():
endpoint = os.environ.get("SELENIUM_ENDPOINT", "http://localhost:4444")
timeout_seconds = int(os.environ.get("SELENIUM_CONNECTION_TIMEOUT", "120"))
config = ClientConfig(
remote_server_addr=endpoint,
timeout=timeout_seconds,
)
executor = RemoteConnection(client_config=config)
options = webdriver.ChromeOptions()
return webdriver.Remote(command_executor=executor, options=options)
driver = make_driver()
try:
driver.get("https://example.com")
finally:
driver.quit()Validate the environment variable before creating the driver in production code: reject non-numeric values, zero, and unexpectedly large values according to your operational policy. The Selenium API itself does not prescribe a universal maximum or an ideal default.
Best Value
Or skip the browser setup
If your real goal is a static screenshot or PDF rather than an interactive Selenium session, ScreenshotNeo can capture a URL through one HTTP request. It is a separate option from Selenium: no browser-driver session is required in your code.
cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython (see the ScreenshotNeo API documentation):
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
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 fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo removes cookie-consent banners, newsletter popups, and chat widgets before capture. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed as clean shots; response headers identify the page verdict and whether the request was billed. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Every feature is available on every plan. Create a free ScreenshotNeo account.
Operational notes for reliable suites
- Keep transport timeout, page-load timeout, script timeout, and explicit waits in separate configuration fields so an incident points to the correct layer.
- Emit the endpoint name, timeout value, exception type, and elapsed time in test logs. Avoid logging credentials embedded in hosted-service URLs.
- Use a bounded timeout in CI. An unreachable Grid should fail clearly rather than consuming worker capacity for an uncontrolled period.
- When latency changes seasonally or by region, measure normal command round trips and adjust environment-specific configuration instead of copying a larger value everywhere.
- After upgrading Selenium, run a small connection test because constructor details and deprecation status can differ between binding versions.
Frequently Asked Questions
What should I record when investigating intermittent connection timeouts?
Record the command-executor URL (without secrets), configured seconds, Python and Selenium versions, elapsed time, exception class, and matching Selenium Server/Grid and node log timestamps. This separates network delay from server-side queueing or browser-start failures.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Should development and CI use the same connection-timeout value?
Not necessarily. Select values from the normal round-trip latency and failure-detection needs of each environment, then keep them in environment configuration rather than hard-coding one value in every test.
Does a successful HTTP connection prove that a browser session is healthy?
No. The endpoint can answer while a Grid node is unavailable or a browser cannot start. Session creation and node-health logs still need to be checked when failures continue.
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.
