FastAPI AttributeError: 'dict' object has no attribute

The Fix

pip install fastapi==0.128.4

Based on closed fastapi/fastapi issue #14344 · PR/commit linked

Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.

Jump to Verify Open PR/Commit

@@ -262,12 +262,12 @@ def _replace_refs(
     for key, value in new_schema.items():
         if key == "$ref":
-            ref_name = schema["$ref"].split("/")[-1]
-            if ref_name in old_name_to_new_name_map:
-                new_name = old_name_to_new_name_map[ref_name]

repro.py

# /// script
# dependencies = [
#   "pydantic",
#   "fastapi[standard]",
#   "starlette",
# ]
# ///

import pydantic
import starlette
import fastapi
from fastapi import FastAPI
import sys
from pydantic import BaseModel, Field, ConfigDict

# print the dependencies to stdout, one per line
print(f'pydantic version = {pydantic.__version__}')
print(f'starlette version = {starlette.__version__}')
print(f'fastapi version = {fastapi.__version__}')
# print python version
print(f'Python version = {sys.version}')


app = FastAPI(title='Logfire')

class ModelWithRef(BaseModel):
    ref: str = Field(validation_alias='$ref', serialization_alias='$ref')
    model_config = ConfigDict(validate_by_alias=True, serialize_by_alias=True)



@app.get('/')
async def read_root() -> ModelWithRef:
    return ModelWithRef(ref='some-ref')

print(app.openapi())

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Upgrade to fixed release\npip install fastapi==0.128.4\nWhen NOT to use: Do not apply this fix if the application does not use JSON Schema attributes named '$ref'.\n\n

Why This Fix Works in Production

Trigger: ❯ uv run main.py
Mechanism: The code incorrectly assumed that the value of the '$ref' key would always be a string
Why the fix works: Fix handling of JSON Schema attributes named "$ref" to prevent AttributeError. (first fixed release: 0.128.4).

Production impact:

If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.

Why This Breaks in Prod

Shows up under Python 3.10 in real deployments (not just unit tests).
The code incorrectly assumed that the value of the '$ref' key would always be a string
Surfaces as: ❯ uv run main.py

Proof / Evidence

GitHub issue: #14344
Fix PR: https://github.com/fastapi/fastapi/pull/14349
First fixed release: 0.128.4
Reproduced locally: No (not executed)
Last verified: 2026-02-08
Confidence: 0.95
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.29

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“This should be fixed by https://github.com/fastapi/fastapi/pull/14349, released in FastAPI 0.121.2 🎉”

@tiangolo · 2025-11-13 · confirmation · source

“See also: https://github.com/fastapi/fastapi/discussions/14196”

@YuriiMotov · 2025-11-13 · source

Failure Signature (Search String)

❯ uv run main.py

Error Message

Stack trace

error.txt

Error Message
-------------
❯ uv run main.py   
Installed 42 packages in 61ms
pydantic version = 2.12.4
starlette version = 0.49.3
fastapi version = 0.121.1
Python version = 3.10.15 (main, Oct 16 2024, 08:33:15) [Clang 18.1.8 ]
Traceback (most recent call last):
  File "/Users/marcelotryle/dev/main.py", line 36, in <module>
    print(app.openapi())
  File "/Users/marcelotryle/.cache/uv/environments-v2/main-84bd05b9e640fe68/lib/python3.10/site-packages/fastapi/applications.py", line 1060, in openapi
    self.openapi_schema = get_openapi(
  File "/Users/marcelotryle/.cache/uv/environments-v2/main-84bd05b9e640fe68/lib/python3.10/site-packages/fastapi/openapi/utils.py", line 504, in get_openapi
    field_mapping, definitions = get_definitions(
  File "/Users/marcelotryle/.cache/uv/environments-v2/main-84bd05b9e640fe68/lib/python3.10/site-packages/fastapi/_compat/main.py", line 292, in get_definitions
    v2_field_maps, v2_definitions = v2.get_definitions(
  File "/Users/marcelotryle/.cache/uv/environments-v2/main-84bd05b9e640fe68/lib/python3.10/site-packages/fastapi/_compat/v2.py", line 249, in get_definitions
    new_mapping, new_definitions = _remap_definitions_and_field_mappings(
  File "/Users/marcelotryle/.cache/uv/environments-v2/main-84bd05b9e640fe68/lib/python3.10/site-packages/fastapi/_compat/v2.py", line 331, in _remap_definitions_and_field_mappings
    new_value = _replace_refs(
  File "/Users/marc
... (truncated) ...

Minimal Reproduction

repro.py

# /// script
# dependencies = [
#   "pydantic",
#   "fastapi[standard]",
#   "starlette",
# ]
# ///

import pydantic
import starlette
import fastapi
from fastapi import FastAPI
import sys
from pydantic import BaseModel, Field, ConfigDict

# print the dependencies to stdout, one per line
print(f'pydantic version = {pydantic.__version__}')
print(f'starlette version = {starlette.__version__}')
print(f'fastapi version = {fastapi.__version__}')
# print python version
print(f'Python version = {sys.version}')


app = FastAPI(title='Logfire')

class ModelWithRef(BaseModel):
    ref: str = Field(validation_alias='$ref', serialization_alias='$ref')
    model_config = ConfigDict(validate_by_alias=True, serialize_by_alias=True)



@app.get('/')
async def read_root() -> ModelWithRef:
    return ModelWithRef(ref='some-ref')

print(app.openapi())

Environment

Python: 3.10

What Broke

The application crashes with an AttributeError when trying to access the OpenAPI schema.

Why It Broke

The code incorrectly assumed that the value of the '$ref' key would always be a string

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

pip install fastapi==0.128.4

When NOT to use: Do not apply this fix if the application does not use JSON Schema attributes named '$ref'.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Fix reference: https://github.com/fastapi/fastapi/pull/14349

First fixed release: 0.128.4

Last verified: 2026-02-08. Validate in your environment.

When NOT to Use This Fix

Do not apply this fix if the application does not use JSON Schema attributes named '$ref'.

Verify Fix

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
Pin production dependencies and upgrade only with a reproducible test that hits the failing path.

Version Compatibility Table

Version	Status
0.128.4	Fixed

Related Issues

No related fixes found.

Cluster: fastapi:configuration-error FastAPI hub FastAPI best practices All hubs All clusters

Related clusters: Data consistency Rate limit Race condition

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.

FastAPI AttributeError: 'dict' object has no attribute 'split' (Fix)