The Fix
pip install fastapi==0.128.4
Based on closed fastapi/fastapi issue #13400 · 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%.
@@ -51,6 +51,22 @@ For example, if the client tries to send a `tool` header with a value of `plumbu
```
+## Disable Convert Underscores
+
+The same way as with regular header parameters, when you have underscore characters in the parameter names, they are **automatically converted to hyphens**.
from typing import Annotated, TypeAlias
from fastapi import FastAPI, Header
from pydantic import BaseModel
app = FastAPI()
class CommonHeaders(BaseModel):
host: str
save_data: bool
if_modified_since: str | None = None
traceparent: str | None = None
x_tag: list[str] = []
CommonHeadersAnnotated: TypeAlias = Annotated[CommonHeaders, Header()]
@app.get("/items/")
async def read_items(headers: CommonHeadersAnnotated):
return headers
@app.get("/items2/")
async def read_items2(x_prd_code: Annotated[str, Header()], headers: CommonHeadersAnnotated):
return headers
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.
Option A — Upgrade to fixed release\npip install fastapi==0.128.4\nWhen NOT to use: This fix is not applicable if you require underscores in header names for compatibility with certain clients.\n\n
Why This Fix Works in Production
- Trigger: Header parameter and model handling does not work as expected
- Mechanism: The underscore characters in header parameter names were not being converted to hyphens in FastAPI's Pydantic models
- Why the fix works: Fixes the bug where underscore characters in header parameter names were not being converted to hyphens in FastAPI's Pydantic models. (first fixed release: 0.128.4).
- 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 underscore characters in header parameter names were not being converted to hyphens in FastAPI's Pydantic models
- Production symptom (often without a traceback): Header parameter and model handling does not work as expected
Proof / Evidence
- GitHub issue: #13400
- Fix PR: https://github.com/fastapi/fastapi/pull/13515
- First fixed release: 0.128.4
- Reproduced locally: No (not executed)
- Last verified: 2026-02-08
- Confidence: 0.95
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.56
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: fastapi
- Fixed: 0.128.4
- Mode: fixed_only
- Outcome: ok
Logs
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“Thanks for the discussion, everyone! Let's split this into two things”
“I'll look into cleaning up the code to fit more within the analyze_param function and then could look into creating a PR for it”
“I will not have time to look into this myself, but it would be good to have this fixed as one should be able to…”
“This is a feature request, not a bug. FastAPI doesn't support it yet.”
Failure Signature (Search String)
- Header parameter and model handling does not work as expected
- traceparent: str | None = None
Copy-friendly signature
Failure Signature
-----------------
Header parameter and model handling does not work as expected
traceparent: str | None = None
Error Message
Signature-only (no traceback captured)
Error Message
-------------
Header parameter and model handling does not work as expected
traceparent: str | None = None
Minimal Reproduction
from typing import Annotated, TypeAlias
from fastapi import FastAPI, Header
from pydantic import BaseModel
app = FastAPI()
class CommonHeaders(BaseModel):
host: str
save_data: bool
if_modified_since: str | None = None
traceparent: str | None = None
x_tag: list[str] = []
CommonHeadersAnnotated: TypeAlias = Annotated[CommonHeaders, Header()]
@app.get("/items/")
async def read_items(headers: CommonHeadersAnnotated):
return headers
@app.get("/items2/")
async def read_items2(x_prd_code: Annotated[str, Header()], headers: CommonHeadersAnnotated):
return headers
What Broke
Swagger UI fails to display headers correctly, leading to confusion in API usage.
Why It Broke
The underscore characters in header parameter names were not being converted to hyphens in FastAPI's Pydantic models
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
pip install fastapi==0.128.4
Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.
Fix reference: https://github.com/fastapi/fastapi/pull/13515
First fixed release: 0.128.4
Last verified: 2026-02-08. Validate in your environment.
When NOT to Use This Fix
- This fix is not applicable if you require underscores in header names for compatibility with certain clients.
Verify Fix
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
- Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
- Pin production dependencies and upgrade only with a reproducible test that hits the failing path.
Version Compatibility Table
| Version | Status |
|---|---|
| 0.128.4 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.