httpx How about attaching original traceback to exceptions

The Fix

Upgrade to version 0.14.2 or later.

Based on closed encode/httpx issue #1172 · PR/commit linked

Production note: Watch p95/p99 latency and retry volume; timeouts can turn into retry storms and duplicate side-effects.

Jump to Verify Open PR/Commit

@@ -356,7 +356,7 @@ def map_exceptions(
 
         message = str(exc)
-        raise mapped_exc(message, **kwargs) from None  # type: ignore
+        raise mapped_exc(message, **kwargs) from exc  # type: ignore

repro.py

@contextlib.contextmanager
def map_exceptions(
    mapping: typing.Mapping[typing.Type[Exception], typing.Type[Exception]],
    **kwargs: typing.Any,
) -> typing.Iterator[None]:
    try:
        yield
    except Exception as exc:
        mapped_exc = None

        for from_exc, to_exc in mapping.items():
            if not isinstance(exc, from_exc):
                continue
            # We want to map to the most specific exception we can find.
            # Eg if `exc` is an `httpcore.ReadTimeout`, we want to map to
            # `httpx.ReadTimeout`, not just `httpx.TimeoutException`.
            if mapped_exc is None or issubclass(to_exc, mapped_exc):
                mapped_exc = to_exc

        if mapped_exc is None:
            raise

        message = str(exc)
        raise mapped_exc(message, **kwargs).with_traceback(exc.__traceback__) from None  # type: ignore

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 maintaining the original exception context is unnecessary.\n\n

Why This Fix Works in Production

Trigger: In [30]: httpx.get('http://notexisthost')
Mechanism: The `map_exceptions` function raised exceptions from None, obscuring the original traceback
Why the fix works: Modifies the `map_exceptions` function to include the underlying httpcore exception tracebacks, improving error visibility. (first fixed release: 0.14.2).

Production impact:

If left unfixed, tail latency can spike under load and surface as timeouts/retries (amplifying incident impact).

Why This Breaks in Prod

The `map_exceptions` function raised exceptions from None, obscuring the original traceback
Surfaces as: In [30]: httpx.get('http://notexisthost')

Proof / Evidence

GitHub issue: #1172
Fix PR: https://github.com/encode/httpx/pull/1199
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.25

Discussion

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

Jump to Sources Open on GitHub

“Just noticed that this tweak is not good enough, as there are some repeat frames in the traceback…”

@j178 · 2020-08-12 · source

“I think this issue is a really important one yup. At the very *least* we should drop from None on our map_exceptions and *always* allow…”

@lovelydinosaur · 2020-08-19 · source

Failure Signature (Search String)

In [30]: httpx.get('http://notexisthost')

Error Message

Stack trace

error.txt

Error Message
-------------
In [30]: httpx.get('http://notexisthost')
Traceback (most recent call last):
  File "<ipython-input-30-7c88a36ce394>", line 1, in <module>
    httpx.get('http://notexisthost')
  File "D:\programs\anaconda3\lib\site-packages\httpx\_api.py", line 170, in get
    trust_env=trust_env,
  File "D:\programs\anaconda3\lib\site-packages\httpx\_api.py", line 96, in request
    allow_redirects=allow_redirects,
  File "D:\programs\anaconda3\lib\site-packages\httpx\_client.py", line 601, in request
    request, auth=auth, allow_redirects=allow_redirects, timeout=timeout,
  File "D:\programs\anaconda3\lib\site-packages\httpx\_client.py", line 621, in send
    request, auth=auth, timeout=timeout, allow_redirects=allow_redirects,
  File "D:\programs\anaconda3\lib\site-packages\httpx\_client.py", line 648, in send_handling_redirects
    request, auth=auth, timeout=timeout, history=history
  File "D:\programs\anaconda3\lib\site-packages\httpx\_client.py", line 684, in send_handling_auth
    response = self.send_single_request(request, timeout)
  File "D:\programs\anaconda3\lib\site-packages\httpx\_client.py", line 719, in send_single_request
    timeout=timeout.as_dict(),
  File "D:\programs\anaconda3\lib\site-packages\httpcore\_sync\http_proxy.py", line 99, in request
    method, url, headers=headers, stream=stream, timeout=timeout
  File "D:\programs\anaconda3\lib\site-packages\httpcore\_sync\
... (truncated) ...

Stack trace

error.txt

Error Message
-------------
File "D:\programs\anaconda3\lib\contextlib.py", line 130, in __exit__
    self.gen.throw(type, value, traceback)
  File "D:\programs\anaconda3\lib\site-packages\httpcore\_exceptions.py", line 12, in map_exceptions
    raise to_exc(exc) from None

Stack trace

error.txt

Error Message
-------------
In [4]: httpx.get('http://doestnotexist')
Traceback (most recent call last):
  File "<ipython-input-4-74881dccb3f2>", line 1, in <module>
    httpx.get('http://doestnotexist')
  File "e:\projects\pycharm\httpx\httpx\_api.py", line 170, in get
    trust_env=trust_env,
  File "e:\projects\pycharm\httpx\httpx\_api.py", line 96, in request
    allow_redirects=allow_redirects,
  File "e:\projects\pycharm\httpx\httpx\_client.py", line 643, in request
    request, auth=auth, allow_redirects=allow_redirects, timeout=timeout,
  File "e:\projects\pycharm\httpx\httpx\_client.py", line 673, in send
    request, auth=auth, timeout=timeout, allow_redirects=allow_redirects,
  File "e:\projects\pycharm\httpx\httpx\_client.py", line 702, in _send_handling_redirects
    request, auth=auth, timeout=timeout, history=history
  File "e:\projects\pycharm\httpx\httpx\_client.py", line 738, in _send_handling_auth
    response = self._send_single_request(request, timeout)
  File "e:\projects\pycharm\httpx\httpx\_client.py", line 772, in _send_single_request
    timeout=timeout.as_dict(),
  File "D:\programs\anaconda3\lib\contextlib.py", line 130, in __exit__
    self.gen.throw(type, value, traceback)
  File "e:\projects\pycharm\httpx\httpx\_exceptions.py", line 359, in map_exceptions
    raise mapped_exc(message, **kwargs).with_traceback(exc.__traceback__) from None  # type: ignore
  File "e:\projects\p
... (truncated) ...

Minimal Reproduction

repro.py

@contextlib.contextmanager
def map_exceptions(
    mapping: typing.Mapping[typing.Type[Exception], typing.Type[Exception]],
    **kwargs: typing.Any,
) -> typing.Iterator[None]:
    try:
        yield
    except Exception as exc:
        mapped_exc = None

        for from_exc, to_exc in mapping.items():
            if not isinstance(exc, from_exc):
                continue
            # We want to map to the most specific exception we can find.
            # Eg if `exc` is an `httpcore.ReadTimeout`, we want to map to
            # `httpx.ReadTimeout`, not just `httpx.TimeoutException`.
            if mapped_exc is None or issubclass(to_exc, mapped_exc):
                mapped_exc = to_exc

        if mapped_exc is None:
            raise

        message = str(exc)
        raise mapped_exc(message, **kwargs).with_traceback(exc.__traceback__) from None  # type: ignore

What Broke

Users experienced unclear exception tracebacks when HTTP requests failed.

Why It Broke

The `map_exceptions` function raised exceptions from None, obscuring the original traceback

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 maintaining the original exception context is unnecessary.

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

Option D — Guard side-effects with OnceOnly Guardrail for side-effects

Mitigate duplicate external side-effects under retries/timeouts/agent loops by gating the operation before calling external systems.

Place OnceOnly between your code/agent and real side-effects (Stripe, emails, CRM, APIs).
Use a stable key per side-effect (e.g., customer_id + action + idempotency_key).
Fail-safe: configure fail-open vs fail-closed based on blast radius and spend risk.

Show example snippet (optional)

onceonly.py

from onceonly import OnceOnly
import os

once = OnceOnly(api_key=os.environ["ONCEONLY_API_KEY"], fail_open=True)

# Stable idempotency key per real side-effect.
# Use a request id / job id / webhook delivery id / Stripe event id, etc.
event_id = "evt_..."  # replace
key = f"stripe:webhook:{event_id}"

res = once.check_lock(key=key, ttl=3600)
if res.duplicate:
    return {"status": "already_processed"}

# Safe to execute the side-effect exactly once.
handle_event(event_id)

See OnceOnly SDK

When NOT to use: Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.

Fix reference: https://github.com/encode/httpx/pull/1199

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 maintaining the original exception context is unnecessary.
Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.

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.
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
0.14.2	Fixed

Related Issues

No related fixes found.

Cluster: httpx:timeout All hubs All clusters

Related clusters: Configuration error Data consistency Other

Sources

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

httpx How about attaching original traceback to exceptions raised in `map_exceptions()` ? (Fix)

The Fix

Why This Fix Works in Production

Why This Breaks in Prod

Proof / Evidence

Discussion

Failure Signature (Search String)

Error Message

Minimal Reproduction

What Broke

Why It Broke

Fix Options (Details)

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

Option D — Guard side-effects with OnceOnly Guardrail for side-effects

Get updates

When NOT to Use This Fix

Verify Fix

Did This Fix Work in Your Case?

Prevention

Version Compatibility Table

Related Issues

Sources