The Fix
pip install urllib3==1.26.7
Based on closed urllib3/urllib3 issue #2065 · PR/commit linked
@@ -0,0 +1 @@
@@ -0,0 +1 @@
+Changed return type of ``HTTPResponse.getheaders()`` method to return a list of key-value tuples to match CPython.
\ No newline at end of file
diff --git a/changelog/1897.feature.rst b/changelog/1897.feature.rst
fix.md
Option A — Upgrade to fixed release\npip install urllib3==1.26.7\nWhen NOT to use: This fix is not applicable if the project relies on deprecated features removed in version 2.0.\n\n
Why This Fix Works in Production
- Trigger: Tracking breaking changes for v2.0
- Mechanism: Adds initial Towncrier news fragments for breaking changes in version 2.0, including changes to the HTTPResponse.getheaders() method to match CPython.
- Why the fix works: Adds initial Towncrier news fragments for breaking changes in version 2.0, including changes to the HTTPResponse.getheaders() method to match CPython. (first fixed release: 1.26.7).
Why This Breaks in Prod
- Triggered by an upgrade/regression window: 1.1.1 breaks; 1.26.7 is the first fixed release.
- Shows up under Python 3.10 in real deployments (not just unit tests).
- Production symptom (often without a traceback): Tracking breaking changes for v2.0
Proof / Evidence
- GitHub issue: #2065
- Fix PR: https://github.com/urllib3/urllib3/pull/2361
- First fixed release: 1.26.7
- Affected versions: 1.1.1
- 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.76
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“Should we turn this into a good first issue? Anyone can add a few news fragments, once merged we can mark them as done above”
“We now use towncrier, so I'm going to repurpose that issue to make sure we record all noteworthy v2 changes as news fragments. That way,…”
“Unfortunately we'll likely have to handle them on a case-by-case basis. Potentially we can keep this issue open so we can remember how we handled…”
“Another breaking change that should be mentioned in the changelog is getheaders() return signature changing.”
Failure Signature (Search String)
- Tracking breaking changes for v2.0
- - [x] https://github.com/urllib3/urllib3/commit/4ff35efb97f68c83b588c0e31d612178776be3d7 Change inner container of HTTPHeaderDict to 'dict'
Copy-friendly signature
signature.txt
Failure Signature
-----------------
Tracking breaking changes for v2.0
- [x] https://github.com/urllib3/urllib3/commit/4ff35efb97f68c83b588c0e31d612178776be3d7 Change inner container of HTTPHeaderDict to 'dict'
Error Message
Signature-only (no traceback captured)
error.txt
Error Message
-------------
Tracking breaking changes for v2.0
- [x] https://github.com/urllib3/urllib3/commit/4ff35efb97f68c83b588c0e31d612178776be3d7 Change inner container of HTTPHeaderDict to 'dict'
Environment
- Python: 3.10
- urllib3: 2.0
What Broke
Users may encounter issues due to removed features and altered method behaviors in version 2.0.
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
pip install urllib3==1.26.7
When NOT to use: This fix is not applicable if the project relies on deprecated features removed in version 2.0.
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/2361
First fixed release: 1.26.7
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- This fix is not applicable if the project relies on deprecated features removed in version 2.0.
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.
- 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.
Version Compatibility Table
| Version | Status |
|---|---|
| 1.1.1 | Broken |
| 1.26.7 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.