SQLModel + Pydantic v2 Annotated[...] aliases on ORM models → TypeError: issubclass() arg 1 must be a class (losing DRY field metadata)

[simonryf]

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 typing import Annotated
from uuid import UUID
from pydantic import Field as PydanticField
from sqlmodel import SQLModel, Field as SQLField

# ---- Reusable alias with Annotated ----
type CreatedByUserId = Annotated[
    UUID,
    PydanticField(description="User who created this resource"),
]

# ---- ORM model using the alias directly ----
class MyModel(SQLModel, table=True):
    id: UUID = SQLField(primary_key=True)
    created_by_user_id: CreatedByUserId = SQLField(foreign_key="auth_user.id", index=True)

Description

🧭 Context / Goal

I define type aliases using typing.Annotated + pydantic.Field(...) to keep all validation rules and descriptions in one place.
I want to:

• Reuse those aliases on DTOs (Create/Update/Info) and my ORM models (table=True),
• So I can access description, max_length, etc. on the ORM fields (e.g., for API, UI, ...), without duplicating Field definitions across DTOs and ORM models.

This worked until I hit a runtime error once I started using those aliases directly on ORM fields.

Traceback (shortened):

File ".../sqlmodel/main.py", line 659, in get_sqlalchemy_type
    if issubclass(type_, Enum):
TypeError: issubclass() arg 1 must be a class

If I replace CreatedByUserId with plain UUID in the ORM model, it works (but I lose my DRY metadata).

🔍 What’s really happening

• field.annotation that SQLModel inspects is not a plain class but an AnnotatedAlias (Pydantic v2).
• SQLModel’s get_sqlalchemy_type does issubclass(type_, Enum) without unwrapping the alias → TypeError.

✅ What I already tried

• Removing unions like UUID | None from the alias → still crashes (so not just Union).
• Keeping aliases only in DTOs and using plain types on ORM models → works but defeats my DRY goal (I’d need to repeat Field descriptions or lose them downstream).

❓ What I’m asking

• Is there a supported way in SQLModel to use Annotated[...] aliases directly on ORM fields (table=True) (and keep metadata)?
• e.g., a helper in SQLModel or recommended pattern to unwrap Pydantic’s Annotated before issubclass()?
• If not, is the recommendation simply: don’t use Annotated[...] types on ORM models and keep them only in DTOs?
• If yes, how do people keep descriptions/constraints DRY between DTOs and ORM? Any pattern to “import” Pydantic Field metadata into SQLField(...)?

💡 Desired outcome

• Single source of truth for field metadata (descriptions, max_length, etc.)
• No runtime crashes 🙂

🗂️ Bigger picture (why I care)

I want to keep:

type Name = Annotated[str, Field(max_length=255, description="Reference name shown in UI")]

…and use it everywhere:

class Thing(ORMModel, table=True):
    name: Name = SQLField(index=True)

class ThingCreate(CreateDTO):
    name: Name

This gives my service layer (and even UI scaffolding) access to the same description without copying it around.

When I switch to plain str in the ORM model, I lose that Field metadata on the ORM instance and have to duplicate it on the DTOs or somewhere else.

Operating System

Linux

Operating System Details

No response

SQLModel Version

0.0.24

Python Version

3.12

Additional Context

No response

[msftcangoblowm]

In Issues, a search for "issubclass" will show others are in the same boat

There are many open issues discussing this issue: sqlmodel#57 sqlmodel#67 sqlmodel#121 sqlmodel#312

Besides the many open issues, there is a PR that would fix this pull/862

Sadly SQLModel maintenance is not occurring in a timely manner. PRs are languishing forever.

There are no good options. A deeply disturbing option is to roll up your sleeves, applying all the important PRs to your own fork.

Almost everyone in this community is capable of applying all the PRs in a fork. Just comes down to motivating someone by pelting them with cash. And thinking of a new package name, rather than SQLModel. Whomever is the target of the mass pelting, they should bring on other maintainers so as not to fall into the same trap.