httpx Relax `HeaderTypes` type alias definition (Fix)

The Fix

Upgrade to version 0.23.1 or later.

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

@@ -3,7 +3,7 @@
 import typing
 import urllib.request
-from collections.abc import MutableMapping
+from collections.abc import Mapping, MutableMapping
 from http.cookiejar import Cookie, CookieJar

repro.py

from collections.abc import Mapping
from typing import Final

_DEFAULT_HEADERS: Final[Mapping[str, str]] = {
    # ...
}

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.23.1 or later.\nWhen NOT to use: This fix should not be used if the intention is to maintain strict type checks with Dict.\n\n

Why This Fix Works in Production

Trigger: This change would placate the type-checker when I do something like the following:
Mechanism: The type alias for HeaderTypes was defined using Dict instead of Mapping, causing type-checking issues
Why the fix works: Replaces `Dict[..., ...]` with `Mapping[..., ...]` in the union definition for `HeaderTypes`, addressing the issue raised in #2314. (first fixed release: 0.23.1).

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 type alias for HeaderTypes was defined using Dict instead of Mapping, causing type-checking issues
Production symptom (often without a traceback): This change would placate the type-checker when I do something like the following:

Proof / Evidence

GitHub issue: #2314
Fix PR: https://github.com/encode/httpx/pull/2317
First fixed release: 0.23.1
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.66

Discussion

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

Jump to Sources Open on GitHub

“https://github.com/encode/httpx/blob/3aa441015820a41861bff9b0e78d787b1a4f2f68/httpx/_types.py#L46-L47 Could Dict be replaced with Mapping in this type definition? This change would placate the type-checker when I do something like the follo”

Issue thread · issue description · source

Failure Signature (Search String)

This change would placate the type-checker when I do something like the following:
If this is acceptable, I'm happy to open a PR for the change. I was about to open a patch but your pull request template text made me think twice because this is more than just

Copy-friendly signature

signature.txt

Failure Signature
-----------------
This change would placate the type-checker when I do something like the following:
If this is acceptable, I'm happy to open a PR for the change. I was about to open a patch but your pull request template text made me think twice because this is more than just fixing a typo despite the tiny change.

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
This change would placate the type-checker when I do something like the following:
If this is acceptable, I'm happy to open a PR for the change. I was about to open a patch but your pull request template text made me think twice because this is more than just fixing a typo despite the tiny change.

Minimal Reproduction

repro.py

from collections.abc import Mapping
from typing import Final

_DEFAULT_HEADERS: Final[Mapping[str, str]] = {
    # ...
}

What Broke

Type-checking errors occurred when using the HeaderTypes alias with immutable dictionaries.

Why It Broke

The type alias for HeaderTypes was defined using Dict instead of Mapping, causing type-checking issues

Fix Options (Details)

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

Upgrade to version 0.23.1 or later.

When NOT to use: This fix should not be used if the intention is to maintain strict type checks with Dict.

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/2317

First fixed release: 0.23.1

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

When NOT to Use This Fix

This fix should not be used if the intention is to maintain strict type checks with Dict.

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.23.1	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.