[BUG] RecursionError in resolve_schema_references() with self-referencing $ref schemas
Author: patelchaitanyCreated Apr 6, 2026Updated Jun 8, 2026
Labelsbug
Describe the bug A clear and concise description of what the bug is.
FastApiMCP crashes with RecursionError when the FastAPI app contains any Pydantic model with a self-referencing (recursive) type definition. The crash occurs during initialization in resolve_schema_references() and prevents the entire MCP server from starting - not just the affected route.
To Reproduce Steps to reproduce the behavior, including example code.
from fastapi import FastAPI
from pydantic import BaseModel
from typing import List, Literal, Optional, Union
from fastapi_mcp import FastApiMCP
class ComparisonFilter(BaseModel):
type: Literal["eq", "ne", "gt", "lt"]
key: str
value: str
class CompoundFilter(BaseModel):
type: Literal["and", "or"]
filters: List[Union[ComparisonFilter, "CompoundFilter"]]
CompoundFilter.model_rebuild()
class SearchRequest(BaseModel):
query: str
filters: Optional[Union[ComparisonFilter, CompoundFilter]] = None
app = FastAPI()
@app.post("/search")
async def search(request: SearchRequest):
return {"status": "ok"}This crashes:
mcp = FastApiMCP(app, name="test", description="test") mcp.mount()
System Info Please specify the relevant information of your work environment.
OS: macOS 26.4 Python: 3.12.12 fastapi-mcp: 0.4.0 fastapi: 0.128.7 pydantic: 2.12.5
Source: tadata-org/fastapi_mcp