Requests Adapter is eating MaxRetriesError's and throwing

The Fix

pip install requests==2.32.0

Based on closed psf/requests issue #6301 · PR/commit linked

Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.

Jump to Verify Open PR/Commit

@@ -1026,8 +1026,30 @@ library to use SSLv3::
                 block=block, ssl_version=ssl.PROTOCOL_SSLv3)
 
+Example: Automatic Retries
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+

repro.py

except MaxRetryError as e:
            if isinstance(e.reason, ConnectTimeoutError):
                # TODO: Remove this in 3.0.0: see #2811
                if not isinstance(e.reason, NewConnectionError):
                    raise ConnectTimeout(e, request=request)

            if isinstance(e.reason, ResponseError):
                raise RetryError(e, request=request)

            if isinstance(e.reason, _ProxyError):
                raise ProxyError(e, request=request)

            if isinstance(e.reason, _SSLError):
                # This branch is for urllib3 v1.22 and later.
                raise SSLError(e, request=request)

            raise ConnectionError(e, request=request)

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Upgrade to fixed release\npip install requests==2.32.0\nWhen NOT to use: This fix is not applicable if you require direct access to MaxRetryError for handling retries.\n\n

Why This Fix Works in Production

Trigger: Adapter is eating MaxRetriesError's and throwing other errors
Mechanism: Requests rethrows exceptions from urllib3, causing confusion in retry logic
Why the fix works: Added an example for implementing automatic retries in the Advanced Usage documentation. (first fixed release: 2.32.0).

Production impact:

If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.

Why This Breaks in Prod

Dependency interaction matters here: urllib3 v1.22.
Requests rethrows exceptions from urllib3, causing confusion in retry logic
Surfaces as: Adapter is eating MaxRetriesError's and throwing other errors

Proof / Evidence

GitHub issue: #6301
Fix PR: https://github.com/psf/requests/pull/6258
First fixed release: 2.32.0
Reproduced locally: No (not executed)
Last verified: 2026-02-08
Confidence: 0.85
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.57

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“> So, that's the issue”

@sigmavirus24 · 2022-12-07 · source

“There's now simple documentation on retries in the Advanced Usage section, added by https://github.com/psf/requests/pull/6258/: https://requests.readthedocs.io/en/latest/user/advanced/#example-automatic-retries It's very basic at the moment but I'm sure mainta”

@matthewarmand · 2023-09-21 · source

“I think you have some fundamental misunderstanding of what's happening but I can't understand what you're actually asking”

@sigmavirus24 · 2022-12-06 · source

“I see”

@robs-nice99 · 2022-12-09 · source

Failure Signature (Search String)

Adapter is eating MaxRetriesError's and throwing other errors

Error Message

Stack trace

error.txt

Error Message
-------------
Adapter is eating MaxRetriesError's and throwing other errors

Minimal Reproduction

repro.py

except MaxRetryError as e:
            if isinstance(e.reason, ConnectTimeoutError):
                # TODO: Remove this in 3.0.0: see #2811
                if not isinstance(e.reason, NewConnectionError):
                    raise ConnectTimeout(e, request=request)

            if isinstance(e.reason, ResponseError):
                raise RetryError(e, request=request)

            if isinstance(e.reason, _ProxyError):
                raise ProxyError(e, request=request)

            if isinstance(e.reason, _SSLError):
                # This branch is for urllib3 v1.22 and later.
                raise SSLError(e, request=request)

            raise ConnectionError(e, request=request)

Environment

urllib3: 1.22

What Broke

Users receive unexpected exceptions instead of MaxRetryError during retries.

Why It Broke

Requests rethrows exceptions from urllib3, causing confusion in retry logic

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

pip install requests==2.32.0

When NOT to use: This fix is not applicable if you require direct access to MaxRetryError for handling retries.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Fix reference: https://github.com/psf/requests/pull/6258

First fixed release: 2.32.0

Last verified: 2026-02-08. Validate in your environment.

When NOT to Use This Fix

This fix is not applicable if you require direct access to MaxRetryError for handling retries.

Verify Fix

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Add a TLS smoke test that performs a real handshake in CI (include CA bundle validation and hostname checks).
Alert on handshake failures by error string and endpoint to catch cert/CA changes quickly.
Make timeouts explicit and test them (unit + integration) to avoid silent behavior changes.
Instrument retries (attempt count + reason) and alert on spikes to catch dependency slowdowns.

Version Compatibility Table

Version	Status
2.32.0	Fixed

Related Issues

No related fixes found.

Cluster: requests:configuration-error Requests hub Requests best practices All hubs All clusters

Related clusters: Data consistency SSL handshake Other

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.

Requests Adapter is eating MaxRetriesError's and throwing other errors (Fix)