The Fix
Upgrade to version 0.7.2 or later.
Based on closed encode/httpx issue #235 · PR/commit linked
Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.
@@ -98,8 +98,12 @@ def __init__(self) -> None:
), "The 'brotlipy' or 'brotli' library must be installed to use 'BrotliDecoder'"
self.decompressor = brotli.Decompressor()
+ self.seen_data = False
def decode(self, data: bytes) -> bytes:
Option A — Upgrade to fixed release\nUpgrade to version 0.7.2 or later.\nWhen NOT to use: Do not apply this fix if the decoder behavior needs to change for non-empty streams.\n\n
Why This Fix Works in Production
- Trigger: Currently if you receive a response with `Content-Encoding: br` set and no body we get an error because Brotli doesn't like being called on an empty stream.
- Mechanism: Brotli decoder fails when called with an empty stream, causing errors
- Why the fix works: Added control to prevent calling decode for empty contents, ensuring decoders handle empty input correctly. (first fixed release: 0.7.2).
- If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.
Why This Breaks in Prod
- Brotli decoder fails when called with an empty stream, causing errors
- Production symptom (often without a traceback): Currently if you receive a response with `Content-Encoding: br` set and no body we get an error because Brotli doesn't like being called on an empty stream.
Proof / Evidence
- GitHub issue: #235
- Fix PR: https://github.com/encode/httpx/pull/237
- First fixed release: 0.7.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.71
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“On reviewing #237 I think we *should* just call into the decoders, but that we should just make sure that all the decoder implementations correctly…”
“More generally: we should make sure not to call *any* decoder if the body is empty.”
Failure Signature (Search String)
- Currently if you receive a response with `Content-Encoding: br` set and no body we get an error because Brotli doesn't like being called on an empty stream.
Copy-friendly signature
Failure Signature
-----------------
Currently if you receive a response with `Content-Encoding: br` set and no body we get an error because Brotli doesn't like being called on an empty stream.
Error Message
Signature-only (no traceback captured)
Error Message
-------------
Currently if you receive a response with `Content-Encoding: br` set and no body we get an error because Brotli doesn't like being called on an empty stream.
What Broke
Empty responses with Brotli encoding lead to application errors.
Why It Broke
Brotli decoder fails when called with an empty stream, causing errors
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
Upgrade to version 0.7.2 or later.
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/237
First fixed release: 0.7.2
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- Do not apply this fix if the decoder behavior needs to change for non-empty streams.
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.
Version Compatibility Table
| Version | Status |
|---|---|
| 0.7.2 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.