httpx Multipart Form Data Headers (Fix)

The Fix

Introduces streaming multipart support, which addresses the issue of incorrect request headers when using multipart forms with an initialized client.

Based on closed encode/httpx issue #2537 · 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%.

Jump to Verify Open PR/Commit

@@ -135,19 +135,18 @@ def __init__(self, name: str, value: FileTypes) -> None:
         self.headers = headers
 
-    def get_length(self) -> int:
+    def get_length(self) -> typing.Optional[int]:
         headers = self.render_headers()

repro.py

import httpx

# Client with Content-Type headers set.
client = httpx.Client(headers={"Content-Type": "application/json"})

# An `application/x-www-form-urlencoded` POST request.
# Essentially the same case as your multipart example, but just a little more simple.
request = client.build_request("POST", "https://www.example.com", data={"a": "b"})

print(request.headers)
print(request.content)

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Apply the official fix\nIntroduces streaming multipart support, which addresses the issue of incorrect request headers when using multipart forms with an initialized client.\nWhen NOT to use: This fix is not applicable if the client should maintain the original Content-Type header.\n\n

Why This Fix Works in Production

Trigger: Error message from our API: `'{"code":"API_MALFORMED_BODY","message":"Malformed JSON"}'`
Mechanism: The request headers are not updated correctly when using an initialized client with multipart forms

Production impact:

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

The request headers are not updated correctly when using an initialized client with multipart forms
Surfaces as: Error message from our API: `'{"code":"API_MALFORMED_BODY","message":"Malformed JSON"}'`

Proof / Evidence

GitHub issue: #2537
Fix PR: https://github.com/encode/httpx/pull/2382
Reproduced locally: No (not executed)
Last verified: 2026-02-11
Confidence: 0.70
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.64

Discussion

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

Jump to Sources Open on GitHub

“Okay, it's a little bit ambiguous what behavior you'd expect in those cases”

@lovelydinosaur · 2023-01-03 · source

Failure Signature (Search String)

Error message from our API: `'{"code":"API_MALFORMED_BODY","message":"Malformed JSON"}'`

Error Message

Stack trace

error.txt

Error Message
-------------
Error message from our API: `'{"code":"API_MALFORMED_BODY","message":"Malformed JSON"}'`

Minimal Reproduction

repro.py

import httpx

# Client with Content-Type headers set.
client = httpx.Client(headers={"Content-Type": "application/json"})

# An `application/x-www-form-urlencoded` POST request.
# Essentially the same case as your multipart example, but just a little more simple.
request = client.build_request("POST", "https://www.example.com", data={"a": "b"})

print(request.headers)
print(request.content)

What Broke

Requests using multipart forms return malformed JSON errors from the API.

Why It Broke

The request headers are not updated correctly when using an initialized client with multipart forms

Fix Options (Details)

Option A — Apply the official fix

Introduces streaming multipart support, which addresses the issue of incorrect request headers when using multipart forms with an initialized client.

When NOT to use: This fix is not applicable if the client should maintain the original Content-Type header.

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

Last verified: 2026-02-11. Validate in your environment.

When NOT to Use This Fix

This fix is not applicable if the client should maintain the original Content-Type header.

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.

Related Issues

No related fixes found.

Cluster: httpx:configuration-error All hubs All clusters

Related clusters: Data consistency Other Timeout

Sources

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