The Fix
Upgrade to version 0.14.2 or later.
Based on closed encode/httpx issue #1188 · PR/commit linked
Production note: Watch p95/p99 latency and retry volume; timeouts can turn into retry storms and duplicate side-effects.
@@ -24,6 +24,7 @@
)
from ._exceptions import (
+ HTTPCORE_EXC_MAP,
CookieConflict,
HTTPStatusError,
repro.py
async def async_get_url(client, url, retry=True):
async with semaphore.get():
try:
response = await client.get(url)
response.raise_for_status()
result = handle_reponse(reponse)
except httpx.RequestError as exc:
if retry:
print(f"Retrying {url} ...")
result = await async_get_url(
client, url, retry=False
)
else:
result = ...
except httpx.HTTPStatusError as exc:
result = ...
return result
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\nUpgrade to version 0.14.2 or later.\nWhen NOT to use: This fix should not be used if the application relies on unhandled exceptions for flow control.\n\n
Why This Fix Works in Production
- Trigger: asyncio.run(run())
- Mechanism: httpcore exceptions were not mapped during response reading in the httpx client
- Why the fix works: Maps httpcore exceptions for Response read methods, addressing issue #1188. (first fixed release: 0.14.2).
Why This Breaks in Prod
- Shows up under Python 3.8 in real deployments (not just unit tests).
- httpcore exceptions were not mapped during response reading in the httpx client
- Surfaces as: Traceback (most recent call last):
Proof / Evidence
- GitHub issue: #1188
- Fix PR: https://github.com/encode/httpx/pull/1190
- First fixed release: 0.14.2
- 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.37
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“Thanks for raising this! Currently we only mapped exceptions happend in Client._send_single_request, your exception occured in Client.send while reading the response, thus not being mapped”
Failure Signature (Search String)
- asyncio.run(run())
Error Message
Stack trace
error.txt
Error Message
-------------
Traceback (most recent call last):
File "/home/user/main.py", line 351, in <module>
asyncio.run(run())
File "/usr/lib64/python3.8/asyncio/runners.py", line 43, in run
return loop.run_until_complete(main)
File "/usr/lib64/python3.8/asyncio/base_events.py", line 616, in run_until_complete
return future.result()
File "/home/user/main.py", line 317, in run
await f
File "/usr/lib64/python3.8/asyncio/tasks.py", line 608, in _wait_for_one
return f.result() # May raise f.exception().
File "/home/user/main.py", line 173, in get_updates
item_api_response = await f
File "/usr/lib64/python3.8/asyncio/tasks.py", line 608, in _wait_for_one
return f.result() # May raise f.exception().
File "/home/user/main.py", line 53, in async_get_url
response = await client.get(url)
File "/home/user/.pyenv/versions/venv/lib64/python3.8/site-packages/httpx/_client.py", line 1292, in get
return await self.request(
File "/home/user/.pyenv/versions/venv/lib64/python3.8/site-packages/httpx/_client.py", line 1143, in request
response = await self.send(
File "/home/user/.pyenv/versions/venv/lib64/python3.8/site-packages/httpx/_client.py", line 1167, in send
await response.aread()
File "/home/user/.pyenv/versions/venv/lib64/python3.8/site-packages/httpx/_models.py", line 958, in aread
self._content = b"".join([part async for part in self.ait
... (truncated) ...
Minimal Reproduction
repro.py
async def async_get_url(client, url, retry=True):
async with semaphore.get():
try:
response = await client.get(url)
response.raise_for_status()
result = handle_reponse(reponse)
except httpx.RequestError as exc:
if retry:
print(f"Retrying {url} ...")
result = await async_get_url(
client, url, retry=False
)
else:
result = ...
except httpx.HTTPStatusError as exc:
result = ...
return result
Environment
- Python: 3.8
What Broke
Users experienced unhandled ReadTimeout exceptions when reading responses.
Why It Broke
httpcore exceptions were not mapped during response reading in the httpx client
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
Upgrade to version 0.14.2 or later.
When NOT to use: This fix should not be used if the application relies on unhandled exceptions for flow control.
Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.
Fix reference: https://github.com/encode/httpx/pull/1190
First fixed release: 0.14.2
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- This fix should not be used if the application relies on unhandled exceptions for flow control.
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 |
|---|---|
| 0.14.2 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.