Free tools Windows power users keep installed
One-click scans. No signup required.
Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
MaxRetryError means urllib3 exhausted its configured attempts to connect to the host and port shown in the traceback; it does not identify the root cause by itself. If that endpoint is localhost or 127.0.0.1 and the path is a WebDriver session command, first check whether Selenium’s local driver service is still running. If the endpoint is a website, proxy, container, or remote Selenium server, investigate that connection instead. The host, port, URL path, nested exception, and failure timing are the fastest way to choose the right fix.
What MaxRetryError and HTTPConnectionPool mean
HTTPConnectionPool names an urllib3 connection pool for a host and, optionally, a port. MaxRetryError means its retry policy was exhausted. The nested error—often phrased as “Failed to establish a new connection”—says more about what went wrong: the connection may have been refused, timed out, or failed for another reason. See the urllib3 connection-pool reference for the meaning of the pool and retry behavior.
In Selenium code, there can be two separate HTTP connections to distinguish:
- Python to WebDriver: Selenium’s client sends commands to a browser driver service, commonly on a local port or at a configured remote Selenium address.
- Browser to target site: the browser loads the URL you asked it to visit. Failures here may appear as browser navigation errors, but do not automatically mean the Python client lost its WebDriver connection.
Do not infer that the target website blocked your scraper just because the traceback says “max retries.” urllib3 documents retry exhaustion; the endpoint and nested exception determine what connection failed.
#1 Best Overall
Read the traceback before changing code
Start with the complete traceback, not just its final line. Note the following details:
- Host and port: Is the request going to
localhost,127.0.0.1, a remote Selenium host, a proxy, or the target website? - URL path: A path containing a WebDriver session command points toward Selenium’s client-to-driver connection. Compare it with the URL your browser is meant to visit.
- Nested exception: “Connection refused,” a timeout, and a proxy error indicate different failure modes.
- Timing: Did it happen while creating the session, or after the browser had already opened and a command was sent?
- Runtime topology: Is Python on the same machine as the driver, or running in a container, VM, or separate host?
A localhost connection-refused example in a Selenium project issue followed a driver crash. That is one documented case, not proof that every similar traceback has the same cause.
Fix the connection based on the endpoint
If the endpoint is a local WebDriver service
When the traceback points to localhost and a WebDriver command, verify that the driver service started and is still accepting connections. Check the driver logs and whether the browser exited or crashed. If the session was already created, a missing driver executable is not automatically the explanation: the service may have stopped later, the browser may have crashed, or your code may be trying to use a session that has ended.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Find the traceback’s local host, port, and WebDriver path.
- Check the Selenium and driver logs at the time of the failure, and confirm whether the browser process is still alive.
- Check your code for commands sent after
driver.quit(), session termination, or an earlier exception that closed the browser. - Re-run a minimal session-creation script to separate driver startup from later navigation or page interaction.
A refused connection is consistent with no process accepting the connection at that address, but inspect logs before deciding why the service stopped.
If Python runs in Docker, a VM, or remotely
In a container or remote setup, localhost refers to the machine or container where the Python process runs. It may not be the machine hosting the browser or WebDriver. Verify the address configured for the remote service, that the relevant port is exposed or reachable from Python’s runtime, and that the service is listening at that endpoint. The exact hostname and networking change depend on your deployment; do not copy a host address from a different container or environment without checking it.
If the failure occurs during driver or session setup
Review the browser, driver, and Selenium setup. Selenium’s installation guide explains that WebDriver communicates through a browser-specific executable and that Selenium Manager can obtain a suitable driver in typical setups with Selenium 4.6 and newer. Check your installed Selenium version, browser version, any custom Service path, and any remote endpoint setting before changing driver configuration: a failure after a session has started calls for a different diagnosis from a failure before one exists.
See Selenium’s browser-driver installation guidance for setup details.
If the endpoint is a proxy or another network host
Do not troubleshoot a remote host as though it were a local driver. Confirm that the host and port in the traceback are the intended proxy or service, and inspect the nested error for refusal, timeout, or proxy-specific failure. Test reachability from the same runtime that runs Python; a host reachable from your laptop may not be reachable from a container or CI worker.
Use Selenium logs and synchronization diagnostics
The Selenium Project’s troubleshooting guidance recommends logging Selenium commands and, when useful, testing across browsers to investigate possible underlying driver faults. It also states: “The most common Selenium-related error is a result of poor synchronization.” That is general Selenium guidance, not a diagnosis of every HTTPConnectionPool error.
Synchronization problems and a lost WebDriver connection are not the same failure. If the traceback shows that the Python client cannot reach the driver service, increasing page waits will not restore that service. If the WebDriver connection remains live but an element or page is not ready, investigate synchronization separately using appropriate waits. Logs and the point of failure help tell these cases apart.
Why adding retries is usually not the fix
Retry settings control how many attempts are made and when urllib3 raises MaxRetryError; they do not restart a stopped WebDriver service or repair an unreachable host. Raising the retry allowance can delay the exception while the underlying failure remains. First identify the endpoint and nested error, then fix the service, runtime networking, or setup that is actually failing. See the urllib3 retry parameters for configuration details.
How to make a minimal Selenium test useful
Use a short, controlled reproduction to establish whether the failure is at session startup or later. Keep the browser and driver configuration the same as in the failing program, but remove unrelated scraping logic, loops, and page interactions. Record whether the session is created, whether a simple navigation succeeds, and which command first triggers the traceback. Preserve the complete traceback and the driver logs; the final exception line alone often lacks the endpoint and nested cause needed to distinguish cases.
For a case-specific diagnosis, the relevant details are the complete traceback, the code around session creation and the failing command, Python/Selenium/urllib3 versions, browser and driver versions, and whether Selenium is local, containerized, or remote. Without those details, the title-level error does not establish one universal fix.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is simply to capture a page rather than interact with it through Selenium, ScreenshotNeo is a website screenshot API and MCP server. A single GET request can return a PNG, JPEG, WebP, or PDF. For example, save this as a shell command after replacing the key and target URL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated 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 matchSee the ScreenshotNeo API documentation for request options. ScreenshotNeo accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and each response identifies the page verdict and billing status in headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Common troubleshooting mistakes
| Symptom or assumption | What to check | Next step |
|---|---|---|
| “Max retries” means the website blocked me | Host, port, URL path, and nested exception in the traceback | Identify which connection failed before changing scraping behavior. |
| Localhost refuses a connection | Whether a driver service is listening and whether the browser/session ended | Inspect driver logs and confirm the code is using a live session. |
| It works locally but fails in a container | What localhost means from the Python process’s runtime |
Verify the remote address and port reachability from that runtime. |
| Retries are increased but the error persists | Whether the endpoint is reachable at all | Fix the service or network issue; retries alone cannot restore it. |
| The error occurs after a browser command | Whether the browser or driver stopped, or code used a closed session | Correlate command logs, session state, and driver logs at the failure time. |
FAQ
Does MaxRetryError prove Selenium’s driver is missing?
No. It proves retries were exhausted for the connection in the traceback. A driver setup issue is one possibility, but the endpoint and timing determine whether it fits.
Should I increase urllib3’s retry count?
Not as the first fix. More retries may make a failed connection take longer to report, but they do not make a stopped or unreachable service available.
Recommended Free Tools
Can a page wait fix a localhost connection-refused error?
Not if Python cannot connect to the WebDriver endpoint. Page synchronization matters when the session is alive and the browser is waiting for page content or an element.
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.
