The Fix
pip install pydantic==2.6.4
Based on closed pydantic/pydantic issue #8628 · 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%.
@@ -36,10 +36,14 @@ def set_discriminator_in_metadata(schema: CoreSchema, discriminator: Any) -> Non
def apply_discriminators(schema: core_schema.CoreSchema) -> core_schema.CoreSchema:
- definitions: dict[str, CoreSchema] | None = None
+ # Throughout recursion, we allow references to be resolved from the definitions
+ # that are present in the outermost schema. Before apply_discriminators is called,
repro.py
import yaml
from typing import Literal, Annotated
from pydantic import Discriminator, TypeAdapter, BaseModel
from pydantic.dataclasses import dataclass
@dataclass(frozen=True, kw_only=True)
class Cat:
type: Literal["cat"] = "cat"
@dataclass(frozen=True, kw_only=True)
class Dog:
type: Literal["dog"] = "dog"
@dataclass(frozen=True, kw_only=True)
class NestedDataClass:
# doesn't work
animal: Annotated[Cat | Dog, Discriminator("type")]
class NestedModel(BaseModel):
# works
animal: Annotated[Cat | Dog, Discriminator("type")]
@dataclass(frozen=True, kw_only=True)
class Root:
data_class: NestedDataClass
model: NestedModel
# works
animal: Annotated[Cat | Dog, Discriminator("type")]
ta = TypeAdapter(Root)
schema1 = ta.json_schema()
print(yaml.dump(schema1))
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\npip install pydantic==2.6.4\nWhen NOT to use: Do not apply this fix if the schema generation does not involve nested dataclasses with discriminators.\n\n
Why This Fix Works in Production
- Trigger: Incorrect JSON schema for discriminated unions in nested dataclasses
- Mechanism: The schema generation for nested dataclasses with discriminators was incorrectly implemented
- Why the fix works: Fix schema build for nested dataclasses / TypedDicts with discriminators to resolve issues with JSON schema generation. (first fixed release: 2.6.4).
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.11 in real deployments (not just unit tests).
- The schema generation for nested dataclasses with discriminators was incorrectly implemented
- Production symptom (often without a traceback): Incorrect JSON schema for discriminated unions in nested dataclasses
Proof / Evidence
- GitHub issue: #8628
- Fix PR: https://github.com/pydantic/pydantic/pull/8950
- First fixed release: 2.6.4
- 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.48
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“@codebutler, Thanks for reporting this! This is definitely a bug. I'll look into a fix for this 👍.”
Failure Signature (Search String)
- Incorrect JSON schema for discriminated unions in nested dataclasses
- With the code below the schema for the nested dataclass looks like:
Copy-friendly signature
signature.txt
Failure Signature
-----------------
Incorrect JSON schema for discriminated unions in nested dataclasses
With the code below the schema for the nested dataclass looks like:
Error Message
Signature-only (no traceback captured)
error.txt
Error Message
-------------
Incorrect JSON schema for discriminated unions in nested dataclasses
With the code below the schema for the nested dataclass looks like:
Minimal Reproduction
repro.py
import yaml
from typing import Literal, Annotated
from pydantic import Discriminator, TypeAdapter, BaseModel
from pydantic.dataclasses import dataclass
@dataclass(frozen=True, kw_only=True)
class Cat:
type: Literal["cat"] = "cat"
@dataclass(frozen=True, kw_only=True)
class Dog:
type: Literal["dog"] = "dog"
@dataclass(frozen=True, kw_only=True)
class NestedDataClass:
# doesn't work
animal: Annotated[Cat | Dog, Discriminator("type")]
class NestedModel(BaseModel):
# works
animal: Annotated[Cat | Dog, Discriminator("type")]
@dataclass(frozen=True, kw_only=True)
class Root:
data_class: NestedDataClass
model: NestedModel
# works
animal: Annotated[Cat | Dog, Discriminator("type")]
ta = TypeAdapter(Root)
schema1 = ta.json_schema()
print(yaml.dump(schema1))
Environment
- Python: 3.11
- Pydantic: 2
What Broke
The generated JSON schema does not match the expected structure, causing integration issues.
Why It Broke
The schema generation for nested dataclasses with discriminators was incorrectly implemented
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
pip install pydantic==2.6.4
When NOT to use: Do not apply this fix if the schema generation does not involve nested dataclasses with discriminators.
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/8950
First fixed release: 2.6.4
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- Do not apply this fix if the schema generation does not involve nested dataclasses with discriminators.
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 |
|---|---|
| 2.6.4 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.