The Fix
pip install pydantic==2.11.0
Based on closed pydantic/pydantic issue #10219 · 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%.
@@ -250,7 +250,6 @@ By leveraging the new [`type` statement](https://typing.readthedocs.io/en/latest
from annotated_types import Gt
- from typing_extensions import TypeAliasType
from pydantic import BaseModel
pydantic version: 2.8.2
pydantic-core version: 2.20.1
pydantic-core build: profile=release pgo=true
install path: /home/aaron/test/venv/lib/python3.12/site-packages/pydantic
python version: 3.12.3 (main, Jul 31 2024, 17:43:48) [GCC 13.2.0]
platform: Linux-6.8.0-41-generic-x86_64-with-glibc2.39
related packages: typing_extensions-4.10.0 fastapi-0.110.0
commit: unknown
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.
Option A — Upgrade to fixed release\npip install pydantic==2.11.0\nWhen NOT to use: Avoid using defaults in type aliases as type checkers may not recognize them.\n\n
Why This Fix Works in Production
- Trigger: attempting to validate without the `items` field provided results in a `Field required [type=missing...` validation error, e.g.:
- Mechanism: The defaulting behavior of fields defined with TypeAliasType fails within discriminated unions
- Why the fix works: upstream changes in 2.11.0 address the mechanism above.
- 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.12 in real deployments (not just unit tests).
- The defaulting behavior of fields defined with TypeAliasType fails within discriminated unions
- Production symptom (often without a traceback): attempting to validate without the `items` field provided results in a `Field required [type=missing...` validation error, e.g.:
Proof / Evidence
- GitHub issue: #10219
- Fix PR: https://github.com/pydantic/pydantic/pull/11475
- First fixed release: 2.11.0
- Reproduced locally: No (not executed)
- Last verified: 2026-02-09
- Confidence: 0.70
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.53
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“So while this is fixed in 2.11, I would discourage having defaults set in a type alias, as type checkers won't be able to understand…”
“Not sure if this helps, but here's the fieldinfo for items using either TypeAlias or the new type syntax: maybe this is related to #6352…”
“totally didn't realize this got fixed - thank you! And understood on the type checkers front. I'll take a look at #11467 and see if…”
“Update: field-specific metadata _won't_ be supported (context available here)”
Failure Signature (Search String)
- attempting to validate without the `items` field provided results in a `Field required [type=missing...` validation error, e.g.:
Copy-friendly signature
Failure Signature
-----------------
attempting to validate without the `items` field provided results in a `Field required [type=missing...` validation error, e.g.:
from pydantic import BaseModel, Discriminator, Field, ValidationError
Error Message
Signature-only (no traceback captured)
Error Message
-------------
attempting to validate without the `items` field provided results in a `Field required [type=missing...` validation error, e.g.:
from pydantic import BaseModel, Discriminator, Field, ValidationError
Minimal Reproduction
pydantic version: 2.8.2
pydantic-core version: 2.20.1
pydantic-core build: profile=release pgo=true
install path: /home/aaron/test/venv/lib/python3.12/site-packages/pydantic
python version: 3.12.3 (main, Jul 31 2024, 17:43:48) [GCC 13.2.0]
platform: Linux-6.8.0-41-generic-x86_64-with-glibc2.39
related packages: typing_extensions-4.10.0 fastapi-0.110.0
commit: unknown
Environment
- Python: 3.12
- Pydantic: 2
What Broke
Validation errors occur when required fields are missing, leading to application crashes.
Why It Broke
The defaulting behavior of fields defined with TypeAliasType fails within discriminated unions
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
pip install pydantic==2.11.0
Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.
Fix reference: https://github.com/pydantic/pydantic/pull/11475
First fixed release: 2.11.0
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- Avoid using defaults in type aliases as type checkers may not recognize them.
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
- 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 |
|---|---|
| 2.11 | Fixed |
| 2.11.0 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.