urllib3 stream() "contract" changed in 1.10.3, can now

The Fix

pip install urllib3==1.25

Based on closed urllib3/urllib3 issue #673 · PR/commit linked

Open PR/Commit

@@ -7,7 +7,7 @@
     import httplib
 from urllib3.response import HTTPResponse
-from urllib3.exceptions import DecodeError, ResponseNotChunked
+from urllib3.exceptions import DecodeError, ResponseNotChunked, ProtocolError

fix.md

Option A — Upgrade to fixed release\npip install urllib3==1.25\nWhen NOT to use: This fix is not suitable if the application relies on IncompleteRead being raised.\n\n

Why This Fix Works in Production

Trigger: stream() "contract" changed in 1.10.3, can now raise IncompleteRead
Mechanism: Fixes the contract of HTTPResponse.stream() by ensuring that HTTPResponse.read_chunked() catches the same low-level exceptions as HTTPResponse.read().
Why the fix works: Fixes the contract of HTTPResponse.stream() by ensuring that HTTPResponse.read_chunked() catches the same low-level exceptions as HTTPResponse.read(). (first fixed release: 1.25).

Production impact:

If left unfixed, this can cause silent data inconsistencies that propagate (bad cache entries, incorrect downstream decisions).

Why This Breaks in Prod

Production symptom (often without a traceback): stream() "contract" changed in 1.10.3, can now raise IncompleteRead

Proof / Evidence

GitHub issue: #673
Fix PR: https://github.com/urllib3/urllib3/pull/674
First fixed release: 1.25
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.85
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.64

Discussion

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

Jump to Sources Open on GitHub

“Hm sorry about that. Are you proposing a specific fix, or is this a request for a major version bump?”

@shazow · 2015-07-14 · source

“The potentially simplest way to handle this is to have our own IncompleteRead error subclass ProtocolError and wrap the IncompleteRead from httplib. (Assuming I'm understanding…”

@sigmavirus24 · 2015-07-14 · source

“I like sigma's suggestion. It preserves the information of the exception while allowing clients to continue to catch the same set of exceptions.”

@kingsawyer · 2015-07-14 · source

“Yea we definitely shouldn't be leaking httplib exceptions in the high-level api.”

@shazow · 2015-07-14 · source

Failure Signature (Search String)

stream() "contract" changed in 1.10.3, can now raise IncompleteRead
In 1.10.2, `HTTPResponse.stream()` always called `HTTPResponse.read()`. This method catches all `HTTPException` (including `IncompleteRead`), and re-raises them as `ProtocolError`.

Copy-friendly signature

signature.txt

Failure Signature
-----------------
stream() "contract" changed in 1.10.3, can now raise IncompleteRead
In 1.10.2, `HTTPResponse.stream()` always called `HTTPResponse.read()`. This method catches all `HTTPException` (including `IncompleteRead`), and re-raises them as `ProtocolError`.

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
stream() "contract" changed in 1.10.3, can now raise IncompleteRead
In 1.10.2, `HTTPResponse.stream()` always called `HTTPResponse.read()`. This method catches all `HTTPException` (including `IncompleteRead`), and re-raises them as `ProtocolError`.

Environment

urllib3: 1.10.4

Fix Options (Details)

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

pip install urllib3==1.25

When NOT to use: This fix is not suitable if the application relies on IncompleteRead being raised.

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

Fix reference: https://github.com/urllib3/urllib3/pull/674

First fixed release: 1.25

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

When NOT to Use This Fix

This fix is not suitable if the application relies on IncompleteRead being raised.

Did This Fix Work in Your Case?

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

Prevention

Add a CI check that diffs key outputs after upgrades (OpenAPI schema snapshots, JSON payload shapes, CLI output).
Upgrade behind a canary and run integration tests against the canary before 100% rollout.

Version Compatibility Table

Version	Status
1.25	Fixed

Related Issues

No related fixes found.

Cluster: urllib3:data-consistency urllib3 hub urllib3 best practices All hubs All clusters

Related clusters: Configuration error SSL handshake Other

Sources

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

urllib3 stream() "contract" changed in 1.10.3, can now raise IncompleteRead (Fix)