The Fix
pip install urllib3==2.2.0
Based on closed urllib3/urllib3 issue #3164 · PR/commit linked
Production note: This tends to surface only under concurrency. Reproduce with load tests and watch for lock contention/cancellation paths.
@@ -12,7 +12,6 @@
import ssl
import tempfile
-import time
import typing
import zlib
repro.py
>> print("OS", platform.platform())
OS Linux-6.5.0-2-amd64-x86_64-with-glibc2.37
>> print("Python", platform.python_version())
Python 3.11.6
>> print(ssl.OPENSSL_VERSION)
OpenSSL 3.0.11 19 Sep 2023
>> print("urllib3", urllib3.__version__)
urllib3 1.26.17 <- but I'm filing this bug against current main (4e98d57809dacab1cbe625fddeec1a290c478ea9)
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 urllib3==2.2.0\nWhen NOT to use: Do not apply this fix if the underlying timeout issue is not addressed.\n\n
Why This Fix Works in Production
- Trigger: __________________ TestContentFraming.test_chunked_specified[file-PUT-True] __________________
- Mechanism: Flaky tests due to low timeout values in socket-level tests
- Why the fix works: Fixes flaky time-based socketlevel tests by relying on expected bytes to determine when to stop calling recv(). (first fixed release: 2.2.0).
Production impact:
- If left unfixed, failures can be intermittent under concurrency (hard to reproduce; shows up as sporadic 5xx/timeouts).
Why This Breaks in Prod
- Shows up under Python 3.11.6 in real deployments (not just unit tests).
- Flaky tests due to low timeout values in socket-level tests
- Surfaces as: __________________ TestContentFraming.test_chunked_specified[file-PUT-True] __________________
Proof / Evidence
- GitHub issue: #3164
- Fix PR: https://github.com/urllib3/urllib3/pull/3206
- First fixed release: 2.2.0
- 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.41
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“I'd like to clarify that I see failures locally too, sorry. I'd like to investigate to understand why they timeout, but in the meantime I'd…”
“In https://github.com/urllib3/urllib3/pull/3165#issuecomment-1794225322 @pquentin says: > Yes, those tests work fine in CI”
Failure Signature (Search String)
- __________________ TestContentFraming.test_chunked_specified[file-PUT-True] __________________
Error Message
Stack trace
error.txt
Error Message
-------------
__________________ TestContentFraming.test_chunked_specified[file-PUT-True] __________________
Traceback (most recent call last):
File "/tmp/urllib3/.nox/test-3-11/lib/python3.11/site-packages/_pytest/runner.py", line 341, in from_call
result: Optional[TResult] = func()
^^^^^^
File "/tmp/urllib3/.nox/test-3-11/lib/python3.11/site-packages/_pytest/runner.py", line 262, in <lambda>
lambda: ihook(item=item, **kwds), when=when, reraise=reraise
^^^^^^^^^^^^^^^^^^^^^^^^
File "/tmp/urllib3/.nox/test-3-11/lib/python3.11/site-packages/pluggy/_hooks.py", line 493, in __call__
return self._hookexec(self.name, self._hookimpls, kwargs, firstresult)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/tmp/urllib3/.nox/test-3-11/lib/python3.11/site-packages/pluggy/_manager.py", line 115, in _hookexec
return self._inner_hookexec(hook_name, methods, kwargs, firstresult)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/tmp/urllib3/.nox/test-3-11/lib/python3.11/site-packages/pluggy/_callers.py", line 152, in _multicall
return outcome.get_result()
^^^^^^^^^^^^^^^^^^^^
File "/tmp/urllib3/.nox/test-3-11/lib/python3.11/site-packages/pluggy/_result.py", line 114, in get_result
raise exc.with_traceback(exc.__traceback__)
File "/tmp/urllib3/.nox/test-3-
... (truncated) ...
Minimal Reproduction
repro.py
>> print("OS", platform.platform())
OS Linux-6.5.0-2-amd64-x86_64-with-glibc2.37
>> print("Python", platform.python_version())
Python 3.11.6
>> print(ssl.OPENSSL_VERSION)
OpenSSL 3.0.11 19 Sep 2023
>> print("urllib3", urllib3.__version__)
urllib3 1.26.17 <- but I'm filing this bug against current main (4e98d57809dacab1cbe625fddeec1a290c478ea9)
Environment
- Python: 3.11.6
- urllib3: 1.26.17
What Broke
Tests fail sporadically, causing unreliable test results in CI and local environments.
Why It Broke
Flaky tests due to low timeout values in socket-level tests
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
pip install urllib3==2.2.0
When NOT to use: Do not apply this fix if the underlying timeout issue is not addressed.
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/3206
First fixed release: 2.2.0
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- Do not apply this fix if the underlying timeout issue is not addressed.
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 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 |
|---|---|
| 2.2.0 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.