httpx add more type checking in params/form-data (Fix)

The Fix

Upgrade to version 0.18.0 or later.

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

@@ -21,6 +21,7 @@
     ResponseContent,
 )
+from ._utils import primitive_value_to_str

repro.py

import httpx


r = httpx.post(
    "https://httpbin.org/post",
    data={
        "content": bytes.fromhex(
            "4f5f13d16da9f10d013933673a1ef4e7b974dbe3"
        ),  # random non-printable bytes
    },
)
print(r.json()["form"])

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.18.0 or later.\nWhen NOT to use: This fix should not be used if the application relies on the previous behavior of accepting all types without conversion.\n\nOption C — Workaround\ncorrectly_encoded_request = client.build_request(\nWhen NOT to use: This fix should not be used if the application relies on the previous behavior of accepting all types without conversion.\n\n

Why This Fix Works in Production

Trigger: >> from urllib.parse import unquote
Mechanism: The library did not properly handle non-string types in form data, leading to incorrect conversions
Why the fix works: Allows integers, floats, booleans, and None as valid values for URLEncoded and Multipart content, converting them appropriately. (first fixed release: 0.18.0).

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

Shows up under Python 3.10 in real deployments (not just unit tests).
The library did not properly handle non-string types in form data, leading to incorrect conversions
Surfaces as: >> from urllib.parse import unquote

Proof / Evidence

GitHub issue: #3170
Fix PR: https://github.com/encode/httpx/pull/1539
First fixed release: 0.18.0
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.75
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.45

Verified Execution

We executed the runnable minimal repro in a temporary environment and captured exit codes + logs.

Status: PASS
Ran: 2026-02-11T16:52:29Z
Package: httpx
Fixed: 0.18.0
Mode: fixed_only
Outcome: ok

Logs

affected (exit=None)

fixed (exit=0)

{'content': "b'O_\\x13\\xd1m\\xa9\\xf1\\r\\x0193g:\\x1e\\xf4\\xe7\\xb9t\\xdb\\xe3'"}

Discussion

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

Jump to Sources Open on GitHub

“there is also another issue, query string should support bytes natively”

@trim21 · 2024-05-31 · source

“> query string should support bytes natively. I'm not convinced by that. Why?”

@lovelydinosaur · 2024-06-03 · source

“> > query string should support bytes natively. > > I'm not convinced by that. Why? because percent encoding can take native bytes as input”

@trim21 · 2024-06-03 · source

“when we say it support "string", it's actually assuming percent encoded bytes is utf8 content”

@trim21 · 2024-06-03 · source

Failure Signature (Search String)

>> from urllib.parse import unquote

Error Message

Stack trace

error.txt

Error Message
-------------
>> from urllib.parse import unquote
>> from urllib.parse import quote
>> quote(unquote('%EE'))  # stdlib behaving similarly
'%EF%BF%BD'
>> unquote('%EE')  # The hex code here isn't a valid UTF-8 codepoint, and is being replaced.
'�'
>> unquote('%EE', errors='strict')  # We'd raise an error if we decoded it with 'strict'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/tom.christie/.pyenv/versions/3.10.6/lib/python3.10/urllib/parse.py", line 667, in unquote
    append(unquote_to_bytes(bits[i]).decode(encoding, errors))
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xee in position 0: unexpected end of data

Stack trace

error.txt

Error Message
-------------
>>> from urllib.parse import unquote
>>> from urllib.parse import quote
>>> quote(unquote('%EE'))  # stdlib behaving similarly
'%EF%BF%BD'
>>> unquote('%EE')  # The hex code here isn't a valid UTF-8 codepoint, and is being replaced.
'�'
>>> unquote('%EE', errors='strict')  # We'd raise an error if we decoded it with 'strict'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/tom.christie/.pyenv/versions/3.10.6/lib/python3.10/urllib/parse.py", line 667, in unquote
    append(unquote_to_bytes(bits[i]).decode(encoding, errors))
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xee in position 0: unexpected end of data

Minimal Reproduction

repro.py

import httpx


r = httpx.post(
    "https://httpbin.org/post",
    data={
        "content": bytes.fromhex(
            "4f5f13d16da9f10d013933673a1ef4e7b974dbe3"
        ),  # random non-printable bytes
    },
)
print(r.json()["form"])

Environment

Python: 3.10

What Broke

Users experienced unexpected behavior when submitting non-string types in form data, causing incorrect data representation.

Why It Broke

The library did not properly handle non-string types in form data, leading to incorrect conversions

Fix Options (Details)

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

Upgrade to version 0.18.0 or later.

When NOT to use: This fix should not be used if the application relies on the previous behavior of accepting all types without conversion.

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

Option C — Workaround Temporary workaround

correctly_encoded_request = client.build_request(

When NOT to use: This fix should not be used if the application relies on the previous behavior of accepting all types without conversion.

Use only if you cannot change versions today. Treat this as a stopgap and remove once upgraded.

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

First fixed release: 0.18.0

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 the previous behavior of accepting all types without conversion.

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.

Version Compatibility Table

Version	Status
0.18.0	Fixed

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.