KeyError: '$ref' in fastapi.openapi.utils.get_openapi #14265
Replies: 10 comments 8 replies
-
|
Could you provide MRE? |
Beta Was this translation helpful? Give feedback.
-
|
Hello I have same problem. Problem When StrEnum is used somehow in Schema when it does mapping it fails to find @ref key, when I just try/except on the line StrEnum doesn´t have @ref in the pydantic model. First suggestion for fix maybe ttry to detect if schema is sublcass of enum: |
Beta Was this translation helpful? Give feedback.
-
|
This hit me as well after upgrading to My API routes are working, but /docs causes this error.
|
Beta Was this translation helpful? Give feedback.
-
|
This problem Hit me as well after upgrading the fast api to >0.120.1
|
Beta Was this translation helpful? Give feedback.
-
|
FastAPI 0.120.x can crash during OpenAPI build when a schema doesn’t produce a “$ref” (often from StrEnum or inline enums). The v2 compat remapper assumes “$ref” exists and raises KeyError. Passing a filtered routes= list into get_openapi can make it worse by creating mismatched components. The goal: unblock /openapi.json and /docs now, then remove the root cause. Workaround A (unblock now) Workaround B (durable) And don’t pass a filtered routes= to get_openapi. Generate for all routes, then filter paths afterward (as in Workaround A) or mark endpoints with include_in_schema=False. |
Beta Was this translation helpful? Give feedback.
-
|
I think there needs to be a fix that supports using |
Beta Was this translation helpful? Give feedback.
-
|
The problem repreduce for me not just for StrEnum, its repreduce for all BaseModel objects |
Beta Was this translation helpful? Give feedback.
-
|
When trying to create an MRE for maintainers, I can successfully put |
Beta Was this translation helpful? Give feedback.
-
|
I'm seeing the same issue starting with
Issue goes away for me if I downgrade to |
Beta Was this translation helpful? Give feedback.
-
|
Can anyone finally share an MRE? |
Beta Was this translation helpful? Give feedback.
This comment has been hidden.
This comment has been hidden.
This comment has been hidden.
This comment has been hidden.
-
|
Could you help provide an MRE? |
Beta Was this translation helpful? Give feedback.
This comment has been hidden.
This comment has been hidden.
-
|
It doesn't raise |
Beta Was this translation helpful? Give feedback.
-
|
I ran the above code with Pydantic 2.6 and Python 3.12 and it does not raise any errors. |
Beta Was this translation helpful? Give feedback.
-
|
This happens for me when I use an empty Enum class. I'm not sure whether this case is allowed by the OpenAPI specification, so it might be my fault. FastAPI 0.120.2, Pydantic 2.11.9 and Starlette 0.49.1 from enum import Enum
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
from pydantic import BaseModel
app = FastAPI()
class PlatformRole(str, Enum):
admin = "admin"
user = "user"
class OtherRole(str, Enum): ...
class User(BaseModel):
username: str
role: PlatformRole | OtherRole
@app.get("/users")
async def get_user() -> User:
return {"username": "alice", "role": "admin"}
# Trigger OpenAPI generation
get_openapi(title="API Docs", version="1.0.0", routes=app.routes) |
Beta Was this translation helpful? Give feedback.
-
|
@YuriiMotov I was able to produce MRE with Python from enum import StrEnum
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class MyModel(BaseModel):
# Using StrEnum base class triggers the bug
some_enum: StrEnum # ← BUG TRIGGER
name: str
@app.post("/endpoint")
async def create_item(model: MyModel) -> dict:
return {"status": "ok"}
if __name__ == "__main__":
# This will raise KeyError: '$ref'
schema = app.openapi()The exact way this appears in my codebase is we have a model that resembles the following: class MyFieldProperty(BaseModel):
name: str
enum_class: Annotated[SkipJsonSchema[type[StrEnum] | None], Field(exclude=True)] = None
# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
# Even with SkipJsonSchema, FastAPI still processes this for model_name_mapThis appears to trigger the error because of the use of the |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
First Check
Commit to Help
Example Code
Description
Getting the error in fastapi version 0.120.3
File "/Documents/projects/attila/src/server.py", line 77, in custom_openapi
openapi_schema = get_openapi(
^^^^^^^^^^^^
File "/Library/Caches/pypoetry/virtualenvs/attila-CXFNd3da-py3.12/lib/python3.12/site-packages/fastapi/openapi/utils.py", line 504, in get_openapi
field_mapping, definitions = get_definitions(
^^^^^^^^^^^^^^^^
File "/Library/Caches/pypoetry/virtualenvs/attila-CXFNd3da-py3.12/lib/python3.12/site-packages/fastapi/_compat/main.py", line 292, in get_definitions
v2_field_maps, v2_definitions = v2.get_definitions(
^^^^^^^^^^^^^^^^^^^
File "/Library/Caches/pypoetry/virtualenvs/attila-CXFNd3da-py3.12/lib/python3.12/site-packages/fastapi/_compat/v2.py", line 249, in get_definitions
new_mapping, new_definitions = _remap_definitions_and_field_mappings(
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/Library/Caches/pypoetry/virtualenvs/attila-CXFNd3da-py3.12/lib/python3.12/site-packages/fastapi/_compat/v2.py", line 310, in _remap_definitions_and_field_mappings
old_name = schema["$ref"].split("/")[-1]
~~~~~~^^^^^^^^
KeyError: '$ref'
Operating System
macOS
Operating System Details
No response
FastAPI Version
0.120.3
Pydantic Version
2.6.4
Python Version
3.12.10
Additional Context
For security purpose wanted to use starlette 0.49.1 which requires fastapi 0.120.x and my current pydantic version is 2.6.4.
Beta Was this translation helpful? Give feedback.
All reactions