FastAPI 0.152.0 has landed with a focused fix for developers who validate request headers through Pydantic models. Previously, validation errors for header parameter models reported the Python field name, such as int_val, which often does not match the actual HTTP header name a client sends, like int-val. That mismatch made error messages harder to trace back to the offending request header. With this release, error output now reports the HTTP header name instead.
- Validation errors for header parameter models now report the HTTP header name (e.g.
int-val) rather than the Python field name (e.g.int_val). - Explicit aliases on header model fields keep their existing behavior, so any alias you defined is still what appears in errors.
- Models configured with
Header(convert_underscores=False)retain their current behavior; the automatic underscore-to-hyphen mapping is not applied in that case. - Pydantic models using
loc_by_alias=Falsealso keep their existing behavior. - The change was contributed by @tiangolo in PR #16538.
For developers, this is a small but practical improvement to the debugging experience of header-driven APIs. FastAPI's convention of converting underscores to hyphens in header names meant the framework's own error messages could point at an identifier that never appears on the wire. Now the reported location matches what a client actually sent, so logs, error responses, and client-side debugging align with the real request. The scoped behavior for aliases, convert_underscores=False, and loc_by_alias=False means teams relying on custom naming semantics will not see their error output silently shift. Upgrading to 0.152.0 is a low-risk step if you validate headers through models and want clearer, more accurate validation feedback.
Source: https://github.com/fastapi/fastapi/releases/tag/0.152.0