FastAPI schema generation fails for models (SQLModel) with forward references

[YuriiMotov]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the SQLModel documentation, with the integrated search.
• I already searched in Google "How to X in SQLModel" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to SQLModel but to Pydantic.
• I already checked if it is not related to SQLModel but to SQLAlchemy.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from fastapi import FastAPI
from sqlmodel import SQLModel


# ==================== Team ====================

class TeamRead(SQLModel):
    id: int

class TeamReadWithHeroes(TeamRead):
    heroes: list["HeroRead"] = []


# ==================== Hero ====================

class HeroRead(SQLModel):
    id: int

class HeroReadWithTeams(HeroRead):
    teams: list[TeamRead] = []

# ==================== App ====================

app = FastAPI()


@app.get("/teams", response_model=list[TeamReadWithHeroes])
async def get_teams():
    pass

Description

FastAPI app fails (pydantic.errors.PydanticUndefinedAnnotation: name 'HeroRead' is not defined) on startup (before I use any endpoints) with this code.

But if I move TeamReadWithHeroes definition below the HeroRead definition then it works well.
I wouldn't like to move it, because I want to group my models to make my code more readable.

With Pydantic models it works well in either case.

Traceback:

Traceback (most recent call last):
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/type_adapter.py", line 190, in __init__
    core_schema = _getattr_no_parents(type, '__pydantic_core_schema__')
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/type_adapter.py", line 98, 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 "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 640, in _resolve_forward_ref
    obj = _typing_extra.evaluate_fwd_ref(obj, globalns=self._types_namespace)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_typing_extra.py", line 425, in evaluate_fwd_ref
    return ref._evaluate(globalns=globalns, localns=localns, recursive_guard=frozenset())
  File "/usr/lib/python3.10/typing.py", line 694, in _evaluate
    eval(self.__forward_code__, globalns, localns),
  File "<string>", line 1, in <module>
NameError: name 'HeroRead' is not defined

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

Traceback (most recent call last):
  File "/usr/lib/python3.10/multiprocessing/process.py", line 314, in _bootstrap
    self.run()
  File "/usr/lib/python3.10/multiprocessing/process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/uvicorn/_subprocess.py", line 76, in subprocess_started
    target(sockets=sockets)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/uvicorn/server.py", line 61, in run
    return asyncio.run(self.serve(sockets=sockets))
  File "/usr/lib/python3.10/asyncio/runners.py", line 44, in run
    return loop.run_until_complete(main)
  File "uvloop/loop.pyx", line 1517, in uvloop.loop.Loop.run_until_complete
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/uvicorn/server.py", line 68, in serve
    config.load()
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/uvicorn/config.py", line 467, in load
    self.loaded_app = import_from_string(self.app)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/uvicorn/importer.py", line 21, in import_from_string
    module = importlib.import_module(module_str)
  File "/usr/lib/python3.10/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1006, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 688, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 883, in exec_module
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "/media/yurii/data/PyProjects/fastapi_course/src/main2.py", line 49, in <module>
    async def get_teams():
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/fastapi/routing.py", line 921, in decorator
    self.add_api_route(
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/fastapi/routing.py", line 860, in add_api_route
    route = route_class(
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/fastapi/routing.py", line 449, in __init__
    self.response_field = create_response_field(
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/fastapi/utils.py", line 99, in create_response_field
    return ModelField(**kwargs)  # type: ignore[arg-type]
  File "<string>", line 6, in __init__
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/fastapi/_compat.py", line 107, in __post_init__
    self._type_adapter: TypeAdapter[Any] = TypeAdapter(
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/type_adapter.py", line 192, in __init__
    core_schema = _get_schema(type, config_wrapper, parent_depth=_parent_depth + 1)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/type_adapter.py", line 81, in _get_schema
    schema = gen.generate_schema(type_)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 468, in generate_schema
    schema = self._generate_schema(obj)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 700, in _generate_schema
    schema = self._post_process_generated_schema(self._generate_schema_inner(obj))
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 707, in _generate_schema_inner
    return self._annotated_schema(obj)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 1586, in _annotated_schema
    schema = self._apply_annotations(source_type, annotations)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 1654, in _apply_annotations
    schema = get_inner_schema(source_type)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_schema_generation_shared.py", line 82, in __call__
    schema = self._handler(__source_type)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 1736, in new_handler
    schema = metadata_get_schema(source, get_inner_schema)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 1732, in <lambda>
    lambda source, handler: handler(source)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_schema_generation_shared.py", line 82, in __call__
    schema = self._handler(__source_type)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 1736, in new_handler
    schema = metadata_get_schema(source, get_inner_schema)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_std_types_schema.py", line 316, in __get_pydantic_core_schema__
    items_schema = handler.generate_schema(self.item_source_type)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_schema_generation_shared.py", line 96, in generate_schema
    return self._generate_schema.generate_schema(__source_type)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 463, in generate_schema
    from_property = self._generate_schema_from_property(obj, obj)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 616, in _generate_schema_from_property
    schema = get_schema(
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/main.py", line 578, in __get_pydantic_core_schema__
    return __handler(__source)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_schema_generation_shared.py", line 82, in __call__
    schema = self._handler(__source_type)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 700, in _generate_schema
    schema = self._post_process_generated_schema(self._generate_schema_inner(obj))
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 722, in _generate_schema_inner
    return self._model_schema(obj)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 541, in _model_schema
    {k: self._generate_md_field_schema(k, v, decorators) for k, v in fields.items()},
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 541, in <dictcomp>
    {k: self._generate_md_field_schema(k, v, decorators) for k, v in fields.items()},
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 886, in _generate_md_field_schema
    common_field = self._common_field_schema(name, field_info, decorators)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 951, in _common_field_schema
    schema = self._apply_annotations(
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 1654, in _apply_annotations
    schema = get_inner_schema(source_type)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_schema_generation_shared.py", line 82, in __call__
    schema = self._handler(__source_type)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 1736, in new_handler
    schema = metadata_get_schema(source, get_inner_schema)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_std_types_schema.py", line 316, in __get_pydantic_core_schema__
    items_schema = handler.generate_schema(self.item_source_type)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_schema_generation_shared.py", line 96, in generate_schema
    return self._generate_schema.generate_schema(__source_type)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 468, in generate_schema
    schema = self._generate_schema(obj)
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 700, in _generate_schema
    schema = self._post_process_generated_schema(self._generate_schema_inner(obj))
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 717, in _generate_schema_inner
    return self.generate_schema(self._resolve_forward_ref(obj))
  File "/media/yurii/data/PyProjects/fastapi_course/.venv/lib/python3.10/site-packages/pydantic/_internal/_generate_schema.py", line 642, in _resolve_forward_ref
    raise PydanticUndefinedAnnotation.from_name_error(e) from e
pydantic.errors.PydanticUndefinedAnnotation: name 'HeroRead' is not defined

Operating System

Linux

Operating System Details

Ubuntu 20.04.6 LTS

SQLModel Version

0.0.14

Python Version

3.10.13

Additional Context

FastAPI version: 0.104.1
Pydantic version: 2.5.2

[ks-mw]

I can reproduce this error.

Windows 10
python 3.10.9
fastapi 0.101.1
pydantic 2.3.0

I have the following additional example. Here, an error-free reordering does not seem to be possible. This is probably because regardless of ordering, one of the types must be a "forward reference" because of the cyclic type referencing.

from fastapi import FastAPI
from pydantic import BaseModel
from typing import TypeAlias

class TypeA(BaseModel):
    problematic_field: "UnionAlias"

class TypeB(BaseModel):
    dummy_field: str

UnionAlias: TypeAlias = Union[TypeA, TypeB]  # Removing the "TypeAlias" annotation doesn't change anything

app = FastAPI()

@app.get("/union_alias")
async def get_something() -> UnionAlias:
    pass

Result: pydantic.errors.PydanticUndefinedAnnotation: name 'UnionAlias' is not defined

If I change the type alias to a TypeAliasType, it runs:

from typing_extensions import TypeAliasType
...
UnionAlias = TypeAliasType("UnionAlias", Union[TypeA, TypeB])

Unfortunately, TypeAliasType is not fully supported by mypy yet (see here and here), so I get many type errors now in our production code, which is why I'd rather like to avoid that one.

[YuriiMotov]

Just checked it on last versions (FastAPI 0.109.2, Pydantic 2.6.1, SQLModel 0.0.16), it works well and doesn't fail.

[ks-mw]

Can confirm. Thank you so much!

[charliejharrison]

I'm having a similar issue with my models split across different files. It seems like Pydantic can't handle not having access to the full class. I found an ugly workaround: see here