Python requests: 'ConnectionError: HTTPSConnectionPool(...): Max retries exceeded with url ... (Caused by NewConnectionError: Failed to establish a new connection / NameResolutionError / ConnectTimeoutError)'. What does it mean and how do I fix it?

Cause: 'Max retries exceeded' is a wrapper from urllib3 (which requests uses). The useful part is the 'Caused by' text at the end: - NameResolutionError / 'Name or service not known' / 'getaddrinfo failed': DNS couldn't resolve the host (typo, no network, container without DNS, wrong internal hostname). - NewConnectionError with 'Connection refused': nothing is listening on that host and port (service down, wrong port, 'localhost' inside a container means the container itself). - ConnectTimeoutError / ReadTimeout: a firewall, proxy or slow server; also the remote service rate-limiting or dropping connections. - SSLError: certificate problems (a different fix). - ProxyError: HTTP(S)_PROXY settings point at a proxy that isn't reachable. By default requests does not retry, so 'max retries' usually means one failed attempt. Fix: 1. Read the 'Caused by' part and test the same URL outside Python: curl -v <url>, and nslookup/dig the host. 2. Containers: use the service name (Docker Compose) or host.docker.internal instead of localhost to reach a service on the host; check the target binds to 0.0.0.0, not 127.0.0.1. 3. Check proxy variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY); requests reads them automatically. Add internal hosts to NO_PROXY. 4. Always set a timeout: requests.get(url, timeout=(5, 30)) (connect, read). Without one, a request can hang forever. 5. For flaky networks or rate-limited APIs, add retries with backoff by mounting an HTTPAdapter with urllib3's Retry (for example total=5, backoff_factor=1, status_forcelist=[429, 500, 502, 503, 504]) on a Session, and reuse that Session. 6. If you hit it under load, you may be opening too many connections: reuse a Session (connection pooling) instead of calling requests.get in a tight loop. Verify: curl reaches the URL from the same machine or container, and the Python call succeeds with a timeout set. Sources: https://requests.readthedocs.io/en/latest/user/advanced/ https://urllib3.readthedocs.io/en/stable/reference/urllib3.util.html