What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
A requests.exceptions.ConnectTimeout means Python Requests did not establish a connection to the remote server within the connection timeout. Set an explicit timeout—usually a separate connect and read value—then check DNS, network reachability, firewalls, and proxy configuration. Add bounded retries only when repeating the request is safe.
What a ConnectTimeout means
Requests defines ConnectTimeout as a timeout while trying to connect to the remote server. It occurs during connection setup, before Requests can read the response body. The exception alone does not identify why setup stalled: possible causes include slow or failing network paths, DNS and routing problems, firewall rules, or an unreachable proxy.
Requests documents that requests producing this particular error are safe to retry. That does not mean every request in your application should be retried without limits; configure retries deliberately and consider what the operation does.
ConnectTimeout vs. ReadTimeout and other errors
| Error | What failed | What to investigate |
|---|---|---|
ConnectTimeout |
Establishing a connection to the remote server took too long. | Connection timeout, DNS, routing, firewall or proxy path. |
ReadTimeout |
A connection was established, but the server did not provide data within the read timeout. | Server response time, read timeout, or the operation being performed. |
ConnectionError |
A broader connection-level failure. | Inspect the chained exception for the underlying network error. |
ProxyError |
The configured proxy could not be used successfully. | Proxy URL, credentials, availability, and destination access. |
| TLS certificate error | TLS certificate validation failed; this is not a connection timeout. | Certificate trust, hostname, system clock, and TLS configuration. |
Requests’ Timeout exception is the parent class for both ConnectTimeout and ReadTimeout. Catch the specific exception when the response affects your recovery behavior; otherwise, catching the parent can handle either timeout. See the Requests exception reference.
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 →#1 Best Overall
Set explicit connect and read timeouts
Requests does not time out by default. Without an explicit timeout, an unresponsive call may wait for minutes or longer. A single numeric timeout applies to both the connection and read phases; a tuple lets you tune them separately. The Requests advanced guide’s example is (3.05, 27): 3.05 seconds to connect and 27 seconds between reads.
import requests
response = requests.get(
"https://api.example.com/health",
timeout=(3.05, 27), # connect timeout, read timeout, in seconds
)
response.raise_for_status()
print(response.status_code)Choose values for your service and network rather than copying a sample blindly. A shorter connect limit makes failures surface sooner but is less tolerant of transient latency. A longer one gives slow connection attempts more time, while delaying failure detection. Requests recommends a connect timeout slightly larger than a multiple of three, reflecting the default TCP retransmission window; it is guidance, not a guarantee that all networks behave alike.
For details, see the Requests timeout documentation and its Quickstart timeout section.
A timeout is not a total-request deadline
The connect timeout limits a connection attempt; it is not a wall-clock cap for the complete operation or for downloading an entire response. The read timeout concerns waiting for data, rather than setting a total download duration. DNS resolution and system conditions can also make elapsed time exceed the nominal connect timeout. If a hostname resolves to multiple IP addresses, connection attempts may occur sequentially, so the total connection phase can take longer than one per-attempt limit.
urllib3’s timeout model similarly describes connect and read limits, not a general end-to-end deadline. If your application requires an overall deadline, enforce that at the application or job level as well as setting Requests timeouts. See the urllib3 Timeout reference.
Diagnose the network path in order
- Record useful context. Log the full exception chain, target scheme, hostname and port, timeout values, and whether a proxy is configured. Redact proxy credentials and other secrets. Note whether the operation is safe to repeat.
- Test DNS from the same environment. Resolve the hostname using the operating system’s DNS tools inside the same host, container, or runtime that runs Python. A name-resolution failure is distinct from a ConnectTimeout, but can expose a broken path to the destination.
- Test destination reachability. Check whether the target port can be reached from that same environment. A refused connection differs from a timeout; either result helps narrow the problem. Requests’ Quickstart error documentation lists DNS failure and refused connection among common network problems.
- Compare direct and proxy routes. If your environment uses a proxy, test the path your application actually takes and verify the proxy can reach the destination. Do not assume a successful test from a developer laptop proves the container or production host has the same route.
- Check infrastructure when tests disagree. If direct checks succeed but the application still times out, investigate container egress rules, firewall policy, NAT capacity, DNS configuration, connection-pool saturation, and service-side allowlists. The exception text cannot identify a local root cause by itself.
Check proxy configuration, including SOCKS DNS behavior
Requests accepts a per-request proxy mapping. Confirm the scheme, hostname, port, authentication, and destination access. Also check environment-level proxy configuration used by your session: an unexpected proxy can change the route even when the request code does not pass a proxies argument.
import requests
proxies = {
"http": "http://proxy.example.com:8080",
"https": "http://proxy.example.com:8080",
}
response = requests.get(
"https://api.example.com/health",
proxies=proxies,
timeout=(3.05, 27),
)
response.raise_for_status()For SOCKS proxies, DNS behavior depends on the scheme. With socks5, the client resolves the destination; socks5h requests remote resolution. urllib3 also documents socks4a for remote resolution. That difference matters when client-side DNS cannot resolve a hostname but the proxy can. Consult the Requests proxy guide and urllib3 SOCKS proxy guidance.
Add bounded retries for safe operations
Requests’ default HTTPAdapter does not retry failed connections: its max_retries default is zero. Use urllib3’s Retry configuration when you want explicit retry conditions and backoff. The example below retries connection failures at most three times, disables read retries, and limits retryable methods to GET, HEAD, and OPTIONS.
from requests import Session
from requests.adapters import HTTPAdapter
from urllib3.util import Retry
retry = Retry(
total=3,
connect=3,
read=0,
backoff_factor=0.5,
allowed_methods=frozenset({"GET", "HEAD", "OPTIONS"}),
)
session = Session()
session.mount("https://", HTTPAdapter(max_retries=retry))
response = session.get(
"https://api.example.com/health",
timeout=(3.05, 27),
)
response.raise_for_status()
print(response.status_code)Retry counts and timeout values are configuration choices, not universal recommendations. A retry can help with transient connection trouble, but it also adds delay and traffic. Keep attempts bounded. Do not automatically retry a state-changing request such as a payment or record creation unless the operation is designed to be safely repeated—for example, through an idempotency mechanism. Requests identifies a ConnectTimeout request as safe to retry, but application-level effects and server behavior still matter. See HTTPAdapter and urllib3 Retry.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Common fixes by symptom
| Symptom | Likely area | Next action |
|---|---|---|
| The request hangs for a long time. | No timeout was set. | Pass an explicit timeout, preferably a (connect, read) tuple. |
| Only the application or container fails. | Different DNS, egress, firewall, NAT, or allowlist configuration. | Run DNS and port-reachability checks from that same runtime; compare its network policy with a working environment. |
| Direct requests work but proxied requests fail. | Proxy route, credentials, or destination access. | Verify the proxy mapping and its access to the target; compare the configured and direct paths. |
| SOCKS proxy cannot resolve the target. | DNS is being resolved on the client. | Check whether the proxy can resolve it and whether a remote-resolution scheme such as socks5h is appropriate. |
| Connection succeeds but the response stalls. | Read phase rather than connection setup. | Handle ReadTimeout separately and choose a read timeout suited to the endpoint. |
| Retries seem to do nothing. | Requests does not retry by default, or the retry policy does not include the relevant failure or method. | Mount an HTTPAdapter with an explicit bounded urllib3 Retry policy and verify its method and error settings. |
| Failures persist despite longer timeouts. | Underlying route or infrastructure fault. | Check DNS, port reachability, firewall and egress policy, NAT capacity, pools, and service allowlists instead of increasing timeouts indefinitely. |
For website screenshots: skip the browser setup
If the connection problem is part of building your own website screenshot pipeline, ScreenshotNeo offers a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. Its clean-shot flow can accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify outcomes with X-Page-Verdict and X-Billed headers. An MCP server provides 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. Every feature is on every plan.
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 parameters and setup. It may be useful when you want the screenshot service to handle browser capture rather than maintaining that browser setup yourself; it does not diagnose or repair a ConnectTimeout in an unrelated Requests call.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsFrequently Asked Questions
Does Requests retry a ConnectTimeout automatically?
No. Requests’ default HTTPAdapter uses zero retries; configure a bounded urllib3 Retry policy if retries are appropriate for the operation.
Can I use one timeout number instead of a tuple?
Yes. A single numeric value applies to both connect and read timeouts; a tuple lets you set them independently.
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.
