Pydantic lazy evaluation of type annotations in python 3.14

The Fix

pip install pydantic==2.12.5

Based on closed pydantic/pydantic issue #12393 · 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

@@ -22,6 +22,7 @@
 from ._docs_extraction import extract_docstrings_from_cls
 from ._import_utils import import_cached_base_model, import_cached_field_info
+from ._internal_dataclass import slots_true
 from ._namespace_utils import NsResolver
 from ._repr import Representation

repro.py

from typing import ClassVar

from pydantic import BaseModel


class Foo(BaseModel, extra="allow"):
    asdf: ClassVar[Bar] # NameError: name 'Bar' is not defined


class Bar: ...

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.12.5\nWhen NOT to use: This fix should not be applied if the model relies on the previous behavior of `extra='allow'.\n\n

Why This Fix Works in Production

Trigger: lazy evaluation of type annotations in python 3.14 does not work on `ClassVar`s when `extra="allow"`
Mechanism: The handling of `__pydantic_extra__` annotations was not properly evaluated for `ClassVar`s with `extra='allow'
Why the fix works: Refactor the handling of `__pydantic_extra__` annotations to ensure proper evaluation, addressing the issue where lazy evaluation does not work on `ClassVar`s when `extra='allow'`. (first fixed release: 2.12.5).

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.14 in real deployments (not just unit tests).
The handling of `__pydantic_extra__` annotations was not properly evaluated for `ClassVar`s with `extra='allow'
Production symptom (often without a traceback): lazy evaluation of type annotations in python 3.14 does not work on `ClassVar`s when `extra="allow"`

Proof / Evidence

GitHub issue: #12393
Fix PR: https://github.com/pydantic/pydantic/pull/12563
First fixed release: 2.12.5
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.95
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.70

Discussion

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

Jump to Sources Open on GitHub

“### Initial Checks - [x] I confirm that I'm using Pydantic V2 ### Description i'm attempting to remove all the from __future__ import annotations imports from my codebase now that it's no longer required in python 3.14, however i ran into t”

Issue thread · issue description · source

Failure Signature (Search String)

lazy evaluation of type annotations in python 3.14 does not work on `ClassVar`s when `extra="allow"`
asdf: ClassVar[Bar] # NameError: name 'Bar' is not defined

Copy-friendly signature

signature.txt

Failure Signature
-----------------
lazy evaluation of type annotations in python 3.14 does not work on `ClassVar`s when `extra="allow"`
asdf: ClassVar[Bar] # NameError: name 'Bar' is not defined

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
lazy evaluation of type annotations in python 3.14 does not work on `ClassVar`s when `extra="allow"`
asdf: ClassVar[Bar] # NameError: name 'Bar' is not defined

Minimal Reproduction

repro.py

from typing import ClassVar

from pydantic import BaseModel


class Foo(BaseModel, extra="allow"):
    asdf: ClassVar[Bar] # NameError: name 'Bar' is not defined


class Bar: ...

Environment

Python: 3.14
Pydantic: 2

What Broke

Users experienced NameError when using ClassVar annotations without future imports.

Why It Broke

The handling of `__pydantic_extra__` annotations was not properly evaluated for `ClassVar`s with `extra='allow'

Fix Options (Details)

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

pip install pydantic==2.12.5

When NOT to use: This fix should not be applied if the model relies on the previous behavior of `extra='allow'.

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

First fixed release: 2.12.5

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

When NOT to Use This Fix

This fix should not be applied if the model relies on the previous behavior of `extra='allow'.

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.12.5	Fixed

Related Issues

No related fixes found.

Cluster: pydantic:configuration-error Pydantic hub Pydantic best practices All hubs All clusters

Related clusters: Data consistency OpenAPI schema Serialization

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.

Pydantic lazy evaluation of type annotations in python 3.14 does not work on `ClassVar`s when (Fix)