FastAPI Pydantic v2, dataclasses, UUID, and

The Fix

pip install fastapi==0.128.5

Based on closed fastapi/fastapi issue #10007 · 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

@@ -0,0 +1,52 @@
@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import uuid

repro.py

from __future__ import annotations

import uuid
from dataclasses import dataclass, field
from typing import List, Union

from fastapi import FastAPI


@dataclass
class Item:
    id: uuid.UUID
    name: str
    price: float
    tags: List[str] = field(default_factory=list)
    description: Union[str, None] = None
    tax: Union[float, None] = None


app = FastAPI()


@app.get("/items/next", response_model=Item)
async def read_next_item():
    return {
        "name": "Island In The Moon",
        "price": 12.99,
        "description": "A place to be be playin' and havin' fun",
        "tags": ["breater"],
    }

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 fastapi==0.128.5\nWhen NOT to use: Do not use standard dataclasses when Pydantic's dataclass extension is available.\n\n

Why This Fix Works in Production

Trigger: uvicorn main:app
Mechanism: Using standard dataclasses with Pydantic v2 and UUIDs leads to import errors
Why the fix works: Added a test to ensure compatibility with Pydantic v2, dataclasses, UUID, and `__annotations__`. (first fixed release: 0.128.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

Dependency interaction matters here: Pydantic v2.
Shows up under Python 3.10 in real deployments (not just unit tests).
Using standard dataclasses with Pydantic v2 and UUIDs leads to import errors
Surfaces as: uvicorn main:app

Proof / Evidence

GitHub issue: #10007
Fix PR: https://github.com/fastapi/fastapi/pull/14477
First fixed release: 0.128.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.25

Discussion

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

Jump to Sources Open on GitHub

“It looks like forward references are resolved from namespaces built from the previous 2 frames https://github.com/pydantic/pydantic/blob/adc657a8b9f0b5191c180fc51005c0bf1fe529db/pydantic/type_adapter.py#L76”

@xouyang1 · 2023-08-06 · confirmation · source

“The code example from initial comment works well with both, Pydantic V1 and Pydantic V2. So, the issue has been resolved and can be closed…”

@YuriiMotov · 2025-07-28 · confirmation · source

“This would need to be handled on the Pydantic side (or at least require some input/changes from them)”

@tiangolo · 2023-08-14 · source

“This now works with the latest Pydantic versions (probably starting with 2.10), I believe since we refactored forward annotations evaluation.”

@Viicos · 2025-03-02 · source

Failure Signature (Search String)

uvicorn main:app

Error Message

Stack trace

error.txt

Error Message
-------------
uvicorn main:app
Traceback (most recent call last):
  File "/Users/user/code/fastapi/env3.10/lib/python3.10/site-packages/pydantic/type_adapter.py", line 165, in __init__
    core_schema = _getattr_no_parents(type, '__pydantic_core_schema__')
  File "/Users/user/code/fastapi/env3.10/lib/python3.10/site-packages/pydantic/type_adapter.py", line 97, in _getattr_no_parents
    raise AttributeError(attribute)
AttributeError: __pydantic_core_schema__

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/user/code/fastapi/env3.10/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 625, in _resolve_forward_ref
    obj = _typing_extra.evaluate_fwd_ref(obj, globalns=self._types_namespace)
  File "/Users/user/code/fastapi/env3.10/lib/python3.10/site-packages/pydantic/_internal/_typing_extra.py", line 423, in evaluate_fwd_ref
    return ref._evaluate(globalns=globalns, localns=localns, recursive_guard=frozenset())
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/typing.py", line 694, in _evaluate
    eval(self.__forward_code__, globalns, localns),
  File "<string>", line 1, in <module>
NameError: name 'uuid' is not defined

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/Users/user/code/fastapi/env3.10/bin/uvicor
... (truncated) ...

Stack trace

error.txt

Error Message
-------------
==================================== ERRORS ====================================
______________________ ERROR collecting tests/test_api.py ______________________
ImportError while importing test module '/__w/flux-restful-api/flux-restful-api/tests/test_api.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
/usr/lib/python3.8/importlib/__init__.py:127: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
tests/test_api.py:6: in <module>
    from fastapi.testclient import TestClient
/usr/local/lib/python3.8/dist-packages/fastapi/__init__.py:7: in <module>
    from .applications import FastAPI as FastAPI
/usr/local/lib/python3.8/dist-packages/fastapi/applications.py:3: in <module>
    from fastapi import routing
/usr/local/lib/python3.8/dist-packages/fastapi/routing.py:20: in <module>
    from fastapi import params
/usr/local/lib/python3.8/dist-packages/fastapi/params.py:4: in <module>
    from pydantic.fields import FieldInfo, Undefined
E   ImportError: cannot import name 'Undefined' from 'pydantic.fields' (/usr/local/lib/python3.8/dist-packages/pydantic/fields.py)

Stack trace

error.txt

Error Message
-------------
from pydantic.fields import FieldInfo, Undefined
ImportError: cannot import name 'Undefined' from 'pydantic.fields' (/env/lib/python3.8/site-packages/pydantic/fields.py)

Minimal Reproduction

repro.py

from __future__ import annotations

import uuid
from dataclasses import dataclass, field
from typing import List, Union

from fastapi import FastAPI


@dataclass
class Item:
    id: uuid.UUID
    name: str
    price: float
    tags: List[str] = field(default_factory=list)
    description: Union[str, None] = None
    tax: Union[float, None] = None


app = FastAPI()


@app.get("/items/next", response_model=Item)
async def read_next_item():
    return {
        "name": "Island In The Moon",
        "price": 12.99,
        "description": "A place to be be playin' and havin' fun",
        "tags": ["breater"],
    }

Environment

Python: 3.10
Pydantic: 2

What Broke

FastAPI fails to start, resulting in application downtime.

Why It Broke

Using standard dataclasses with Pydantic v2 and UUIDs leads to import errors

Fix Options (Details)

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

pip install fastapi==0.128.5

When NOT to use: Do not use standard dataclasses when Pydantic's dataclass extension is available.

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

First fixed release: 0.128.5

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

When NOT to Use This Fix

Do not use standard dataclasses when Pydantic's dataclass extension is available.

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

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

Related Issues

No related fixes found.

Cluster: fastapi:configuration-error FastAPI hub FastAPI best practices All hubs All clusters

Related clusters: Data consistency Rate limit Race condition

Sources

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

FastAPI Pydantic v2, dataclasses, UUID, and `__annotations__` (Fix)

The Fix

Why This Fix Works in Production

Why This Breaks in Prod

Proof / Evidence

Discussion

Failure Signature (Search String)

Error Message

Minimal Reproduction

Environment

What Broke

Why It Broke

Fix Options (Details)

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

Get updates

When NOT to Use This Fix

Verify Fix

Did This Fix Work in Your Case?

Prevention

Version Compatibility Table

Related Issues

Sources

FastAPI Pydantic v2, dataclasses, UUID, and `annotations` (Fix)