FastAPI: The production pitfalls checklist

Experience is mostly a list of mistakes you no longer make. This part collects thirty that FastAPI teams have paid for in production, grouped by area, each with the symptom you would actually see and the fix. Nine of the least obvious are demonstrated below on the installed FastAPI, because several of them fail silently. Use the list as a code-review and pre-release checklist.

1. Nine silent surprises, demonstrated

each line is a pitfall from the tables below (number in front)

import warnings
from contextlib import asynccontextmanager
from datetime import datetime
from typing import Annotated
from fastapi import Depends, FastAPI, Query
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
from pydantic import BaseModel

# 25: an on_event handler next to a lifespan never runs
ran = []
@asynccontextmanager
async def lifespan(app):
    ran.append("lifespan")
    yield

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    legacy_app = FastAPI(lifespan=lifespan)

    @legacy_app.on_event("startup")
    async def warm_cache():
        ran.append("on_event: warm_cache")
with TestClient(legacy_app):
    pass
print(f"#25 startup handlers that ran: {ran}   (warnings: {len(caught)} DeprecationWarning)")

app = FastAPI()

class UserOut(BaseModel):
    id: int
    email: str

USER = {"id": 1, "email": "[email protected]", "password_hash": "$2b$12$Qx…"}

@app.get("/typed")
def typed() -> UserOut:
    return USER

@app.get("/manual")
def manual() -> UserOut:
    return JSONResponse(USER)                          # 12: bypasses the return type entirely

@app.get("/search")
def search(tags: list[str] = []):                      # 14: without Query() this is a *body* field
    return {"tags": tags}

@app.get("/search-fixed")
def search_fixed(tags: Annotated[list[str], Query()] = []):
    return {"tags": tags}

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

@app.get("/users/me")                                  # 15: declared too late, never reached
def get_me():
    return {"me": True}

@app.post("/orders/")
def create_order():
    return {"created": True}

@app.get("/greet")
def greet(name: str | None):                           # 17: "can be None" is not "optional"
    return {"hello": name}

@app.get("/when")
def when():
    return {"naive": datetime(2026, 9, 19, 10, 0),     # 18: which timezone is this?
            "aware": datetime.fromisoformat("2026-09-19T10:00:00+05:30")}

counter = []
def new_request_number() -> int:
    counter.append(1)
    return len(counter)

@app.get("/numbers")
def numbers(a: Annotated[int, Depends(new_request_number)],
            b: Annotated[int, Depends(new_request_number)],      # 19: cached, same value as a
            c: Annotated[int, Depends(new_request_number, use_cache=False)]):
    return [a, b, c]

class Item(BaseModel):
    name: str

@app.post("/items")
def add_item(item: Item):
    return item

c = TestClient(app)
print("#12 typed return: ", c.get("/typed").json())
print("    JSONResponse: ", c.get("/manual").json())
print("#14 ?tags=a&tags=b ->", c.get("/search?tags=a&tags=b").json(), " with Query():", c.get("/search-fixed?tags=a&tags=b").json())
r = c.get("/users/me")
print("#15 GET /users/me ->", r.status_code, r.json()["detail"][0]["msg"])
r = c.post("/orders", follow_redirects=False)
print("#16 POST /orders  ->", r.status_code, "redirect to", r.headers["location"])
r = c.get("/greet")
print("#17 GET /greet    ->", r.status_code, r.json()["detail"][0]["msg"])
print("#18 datetimes     ->", c.get("/when").json())
print("#19 three Depends ->", c.get("/numbers").json())
r = c.post("/items", content='{"name": "tea"}', headers={"Content-Type": "text/plain"})
print("#27 JSON sent as text/plain ->", r.status_code, r.json()["detail"][0]["msg"][:48] + "…")

Output

#25 startup handlers that ran: ['lifespan']   (warnings: 2 DeprecationWarning)
#12 typed return:  {'id': 1, 'email': '[email protected]'}
    JSONResponse:  {'id': 1, 'email': '[email protected]', 'password_hash': '$2b$12$Qx…'}
#14 ?tags=a&tags=b -> {'tags': []}  with Query(): {'tags': ['a', 'b']}
#15 GET /users/me -> 422 Input should be a valid integer, unable to parse string as an integer
#16 POST /orders  -> 307 redirect to http://testserver/orders/
#17 GET /greet    -> 422 Field required
#18 datetimes     -> {'naive': '2026-09-19T10:00:00', 'aware': '2026-09-19T10:00:00+05:30'}
#19 three Depends -> [1, 1, 2]
#27 JSON sent as text/plain -> 422 Input should be a valid dictionary or object to …

2. Async and concurrency

3. Data and the database

4. The API contract

5. Security

6. Operations and upgrades

7. The pre-release checklist

Recap