Python "requests.exceptions.ConnectionError: Max retries exceeded" in CI

requests.exceptions.ConnectionError: Max retries exceeded with url wraps an underlying urllib3 connection failure: DNS resolution failure, connection refused, or a network timeout. requests has retried up to its limit and given up.

What this error means

A test or step fails with "requests.exceptions.ConnectionError: HTTPSConnectionPool(host=...): Max retries exceeded with url: ...".

python

requests.exceptions.ConnectionError: HTTPSConnectionPool(host='api.example.com', port=443): Max retries exceeded with url: /v1/data

Common causes

The host is unreachable or DNS fails on the runner

The CI network could not resolve or connect to the host, or the service was down.

A service container had not started yet

The test ran before a dependent container was accepting connections.

How to fix it

Wait for readiness and retry transient connects

Confirm the host and port are reachable from the runner (resolve and connect).
For local dependencies, gate the requests on a readiness/health check.
Mock external HTTP in unit tests so they do not depend on live connectivity.

Python

import requests
from requests.adapters import HTTPAdapter, Retry

s = requests.Session()
s.mount("https://", HTTPAdapter(max_retries=Retry(total=5, backoff_factor=0.5)))

How to prevent it

Latchkey managed runners auto-retry transient connection failures, so a brief network or DNS blip does not immediately fail the build.
Mock outbound HTTP in unit tests.
Gate integration tests on dependency readiness checks.