The Fix
Upgrade to version 0.13.0 or later.
Based on closed encode/httpx issue #768 · PR/commit linked
Production note: Watch p95/p99 latency and retry volume; timeouts can turn into retry storms and duplicate side-effects.
@@ -173,7 +173,7 @@ with httpx.Client(app=app, base_url="http://testserver") as client:
```
-For some more complex cases you might need to customize the WSGI dispatch. This allows you to:
+For some more complex cases you might need to customize the WSGI transport. This allows you to:
repro.py
def send(request: Request, timeout: Timeout = None) -> Response:
...
def close():
...
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.13.0 or later.\nWhen NOT to use: This fix should not be used if the existing dispatcher API is still required for compatibility.\n\n
Why This Fix Works in Production
- Trigger: Transport API
- Mechanism: The dispatcher API was incorrectly named and needed to be renamed to transport API
- Why the fix works: Renames the dispatcher API to transport API and promotes the URLLib3Transport to public API, addressing the issue of customizing the transport mechanism. (first fixed release: 0.13.0).
Why This Breaks in Prod
- The dispatcher API was incorrectly named and needed to be renamed to transport API
- Production symptom (often without a traceback): def send(request: Request, timeout: Timeout = None) -> Response:
Proof / Evidence
- GitHub issue: #768
- Fix PR: https://github.com/encode/httpx/pull/963
- First fixed release: 0.13.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.72
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“There's other potentially productive points of collaboration here too, since httpcore would be a nice minimal dependency for other client libs to use for their…”
“> I can't express how excited I am about this”
“Tangentially related to prior renames/rebrands, the https://pypi.org/project/requests-async/ and https://pypi.org/project/http3/ projects should have their documentation updated to point to https://pypi.org/project/httpx/ / https://www.python-httpx.org/”
“Here we go... 👉 https://www.encode.io/httpcore/”
Failure Signature (Search String)
- Transport API
Copy-friendly signature
signature.txt
Failure Signature
-----------------
def send(request: Request, timeout: Timeout = None) -> Response:
def send(self, method: bytes, url: Typle[bytes, bytes, int, bytes], headers: List[Tuple[bytes, bytes]], body: ClosableIterator[bytes] = None, timeout: Timeout = None):
Error Message
Signature-only (no traceback captured)
error.txt
Error Message
-------------
def send(request: Request, timeout: Timeout = None) -> Response:
def send(self, method: bytes, url: Typle[bytes, bytes, int, bytes], headers: List[Tuple[bytes, bytes]], body: ClosableIterator[bytes] = None, timeout: Timeout = None):
Minimal Reproduction
repro.py
def send(request: Request, timeout: Timeout = None) -> Response:
...
def close():
...
What Broke
Users were unable to customize the transport mechanism effectively, leading to confusion.
Why It Broke
The dispatcher API was incorrectly named and needed to be renamed to transport API
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
Upgrade to version 0.13.0 or later.
When NOT to use: This fix should not be used if the existing dispatcher API is still required for compatibility.
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)
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/963
First fixed release: 0.13.0
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- This fix should not be used if the existing dispatcher API is still required for compatibility.
- 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.
- 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.13.0 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.