Skip to content

[BUG] RecursionError in resolve_schema_references() with self-referencing $ref schemas #287

@patelchaitany

Description

@patelchaitany

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions