fastapi-x-4

---

name: fastapi slug: fastapi version: 1.0.1 changelog: "Full coverage pass: deeper guides, situation-named files, and per-user configuration" description: >- Builds, debugs, and hardens FastAPI services: async endpoints, Pydantic models, dependency injection, auth, and deployment. Use when writing or reviewing a FastAPI app, router, or schema; when the API hangs or every route slows because a sync driver or CPU work blocks the event loop; when a request returns an unexpected 422, a POST becomes a 307, or a 500 arrives with no CORS headers; when migrating pydantic v1 to v2 (model_dump, from_attributes, field_validator); when Depends runs too often, yield cleanup misfires, or dependency overrides do not take; when SQLAlchemy raises QueuePool limit or MissingGreenlet, or connections leak across workers; when TestClient, httpx AsyncClient, or pytest-asyncio fail with a closed event loop; when uvicorn or gunicorn workers, graceful shutdown, root_path, or proxy headers need deciding; or when background tasks, WebSockets, SSE, uploads, or the OpenAPI docs misbehave. Not for Django, Flask, or general Python — django, flask, py. homepage: https://clawic.com/skills/fastapi metadata: clawdbot: emoji: ⚡ requires: bins: - python3 os: - linux - darwin - win32 displayName: FastAPI configPaths: - ~/Clawic/data/fastapi/

---

User preferences live in ~/Clawic/data/fastapi/config.yaml (see Configuration); nothing else is stored on the user's machine. If you have data at an old location (~/fastapi/ or ~/clawic/fastapi/), move it to ~/Clawic/data/fastapi/.

When To Use

• Writing or reviewing FastAPI code: routers, dependencies, request/response models, middleware
• Diagnosing latency and stalls: one blocking call, an exhausted pool, a saturated threadpool
• Modelling data at the edge: validation errors, serialization, ORM objects, pydantic v1 → v2
• Wiring auth, settings, database sessions, and background work into the dependency graph
• Getting a service to production: workers, proxies, shutdown, health checks, logging, limits
• Fixing tests that pass wrongly, hang, or die with a closed event loop
• Not for Django, Flask, or plain-Python problems — django, flask, py own those

Quick Reference

Situation	Play
Every route got slow at once, health check included	The loop is blocked: a sync call inside async def, or all threadpool slots busy → async.md
Choosing def vs async def for an endpoint	Any blocking call in the body → def; all-await → async def → async.md
CPU work, image processing, big parsing in a request	Off the loop and off the threadpool: process pool or queue → async.md
422 on a request that looks correct	Read loc in the error body: alias, nesting, or a nullable field with no default → pydantic.md
.dict(), parse_obj, @validator, orm_mode no longer work	Pydantic v2 renames and behavior changes → pydantic.md
ORM instance will not serialize into the response	from_attributes plus a response model, or return the model you declared → pydantic.md
Depends runs more or fewer times than expected	Per-request cache, use_cache=False, singletons in lifespan → dependencies.md
Current user, scopes, tokens, password hashing	auth.md
/users/me hits the {user_id} route; 307 on POST; router prefixes	Declaration order and trailing slashes → routing.md
Where files go, circular imports, app factory, one app or many	structure.md
Env var ignored, secret in the wrong place, per-environment config	settings.md
Sessions, pools, transactions, N+1, migrations, async ORM errors	database.md
Error bodies inconsistent, custom handlers, validation error shape	errors.md
CORS headers missing, middleware order, request IDs, body read twice	middleware.md
Tests: dependency overrides, lifespan, async client, DB isolation	testing.md
Workers, gunicorn vs uvicorn, root_path, graceful shutdown, containers	deployment.md
Slow under load with the loop healthy: serialization, caching, pagination	performance.md
Large uploads or downloads, SSE, streaming JSON, client disconnects	streaming.md
WebSocket drops, broadcast across workers, authenticating a socket	websockets.md
Work after the response: BackgroundTasks vs a real queue, retries	background.md
Docs wrong or missing, generated clients, operation ids, examples	openapi.md
Logs with no request context, health vs readiness, metrics, tracing	observability.md
Ownership checks, mass assignment, SSRF, path traversal, security headers	security.md
Server-rendered HTML: Jinja2, forms, HTMX partials, static files	templates.md
Anything else	Reproduce in one file: one route, no middleware, no DB — then add back one layer at a time until it breaks

Each file is one sub-job and self-contained: read SKILL.md by default, open exactly one guide when the situation matches.

Core Rules

1. async def obliges the whole chain to await. One blocking call inside an async endpoint — psycopg2, requests, time.sleep, a large open().read() — freezes every concurrent request on that worker, not just its own. If any step blocks and cannot be replaced, declare the endpoint def and let Starlette move it to the threadpool.
2. The threadpool has 40 slots per worker. Every def endpoint and def dependency shares AnyIO's default limiter of 40 threads: ceiling = 40 concurrent blocking calls per worker process, the 41st waits with no error message. Concurrency budget = 40 × workers; raise total_tokens in lifespan only after measuring.
3. Dependencies cache per request, singletons live in lifespan. Depends(get_x) used in three places runs once per request and again on the next one. Anything that must exist once per process — DB engine, HTTP client, cache client — is created in the lifespan handler and stored on app.state; @lru_cache on a factory is the escape hatch for cheap, argument-free objects like settings.
4. Validate at the edge, exactly twice. Request model in, response model out, plain objects in between. response_model re-validates everything you return, so a response is a second full validation pass — worth it as a contract, and skippable (response_model=None plus an explicit Response) only on a route you have profiled.
5. Size the pool against the database, not the app. SQLAlchemy defaults to pool_size=5, max_overflow=10 = 15 connections per process, so total = workers × 15. Four workers = 60 of Postgres's default 100 max_connections; a second replica of the same service exhausts the server and every route starts failing on connect.
6. One event loop and one memory space per worker. Lifespan runs once per worker, so 4 workers means 4 pools, 4 in-process caches, and 4 disjoint sets of WebSocket clients. Any state two requests must share goes to Redis or the database — a module-level dict is a per-process cache with a 1-in-N hit rate.
7. Every outbound call carries a timeout. httpx.AsyncClient(timeout=5.0), DB statement timeouts, lock acquisition bounds. Without one, a hung upstream converts into an unbounded queue of pending tasks and the worker dies holding requests it will never answer.
8. Raise errors, never return them from helpers. raise HTTPException(404, ...) travels through the exception handlers and produces the same body everywhere; a JSONResponse returned from a service function only works if the endpoint happens to pass it through, and it skips every handler and response-model check.
9. Middleware order is the reverse of registration. The last add_middleware call is the outermost layer. CORS registered first ends up innermost, so a 500 raised above it reaches the browser with no CORS headers and the real error is invisible in devtools — register CORS last, and add an exception handler so failures are returned rather than propagated.

Version Floors

Behavior that changed with the framework, stated as the floor that gates it. Guides carry additional floors inline in the same form.

Feature	Needs
Return-type annotation used as the response model	fastapi >=0.89
lifespan context manager (replaces @app.on_event)	fastapi >=0.93
Annotated[X, Depends(...)] dependency style	fastapi >=0.95
Pydantic v2 models and model_config	fastapi >=0.100
yield dependency resources no longer usable inside BackgroundTasks	fastapi >=0.106
fastapi dev / fastapi run CLI (fastapi[standard])	fastapi >=0.111
BaseSettings moved to the separate pydantic-settings package	pydantic >=2.0
asyncio.TaskGroup and asyncio.timeout for fan-out and deadlines	python >=3.11

Error Signatures

Signature	Cause	Go to
422 with "loc": ["body", ...]	Body does not match the model: alias, nesting depth, or a nullable field that is required in pydantic v2	pydantic.md
307 Temporary Redirect on POST	Trailing-slash mismatch; method and body survive the redirect, but a proxy with wrong scheme headers sends the client to http://	routing.md
500 in the browser with no CORS headers	Exception escaped above CORSMiddleware (rule 9)	middleware.md
QueuePool limit of size 5 overflow 10 reached	Sessions never closed, or the pool sized without counting workers (rule 5)	database.md
MissingGreenlet / greenlet_spawn has not been called	Lazy relationship access outside an await in async SQLAlchemy	database.md
asyncpg ... another operation is in progress	One connection or session shared by concurrent tasks	database.md
RuntimeError: Event loop is closed in tests	Session-scoped async fixture bound to a function-scoped loop	testing.md
FastAPIError: Invalid args for response field	A non-pydantic type used as response_model	pydantic.md
Endpoint hangs waiting for the body	Middleware consumed the request stream and passed the exhausted receive down	middleware.md
SSE or streamed response arrives only at the end	Proxy buffering the response	streaming.md
WebSocket closes with 1006, never 1000	Abnormal close: proxy idle timeout or worker restart, not application logic	websockets.md
Everything returns 200 but clients time out	Worker saturated: blocked loop or full threadpool (rules 1-2)	async.md

Output Gates

Before delivering FastAPI code, verify:

• No blocking call inside an async def path; blocking work is in a def endpoint, run_in_threadpool, or a queue
• Every outbound HTTP, database, and lock call has an explicit timeout
• Request and response models declared; ORM objects only cross the boundary through a model with from_attributes
• workers × (pool_size + max_overflow) fits inside the database connection limit
• Configuration and secrets read through the settings object, never os.getenv scattered through handlers
• Auth applied at router level with health, readiness, and metrics endpoints excluded
• Every read and write filtered by owner or tenant inside the query, not in a separate if
• Errors raised as HTTPException with a consistent body; no stack trace, SQL, or upstream payload in detail
• Request body size and upload size bounded somewhere (proxy or middleware), not left unlimited
• Tests override dependencies instead of patching, and run inside the lifespan

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/fastapi/config.yaml. Never interview the user — record a preference the moment it is stated.

Variable	Type	Default	Effect
pydantic_version	1 | 2	2	Which API names appear everywhere: model_dump vs .dict(), field_validator vs validator, settings package (pydantic.md)
db_stack	sqlalchemy-async | sqlalchemy-sync | sqlmodel | tortoise | none	sqlalchemy-async	Session and engine pattern, driver choice, and whether endpoints are emitted def or async def (database.md)
server_stack	uvicorn | gunicorn-uvicorn | hypercorn	uvicorn	Process model, worker flags, and shutdown settings (deployment.md)
auth_scheme	jwt | session-cookie | oauth2-provider | api-key | none	jwt	Which current-user dependency and token lifecycle auth.md emits
min_fastapi	text (version, e.g. 0.100)	0.111	Gates the Version Floors features; below the floor the fallback form is emitted instead
deploy_target	container | vm | serverless | unknown	container	Worker model, health-check style, and shutdown guidance (deployment.md, observability.md)
error_envelope	bare | enveloped	bare	Shape of every error body and the handlers generated in errors.md
task_backend	background-tasks | celery | arq | rq | dramatiq	background-tasks	Where after-response work goes and how failures are retried (background.md)
test_client	async-httpx | testclient	async-httpx	Shape of emitted tests, fixtures, and the transport used (testing.md)
json_renderer	default | orjson	default	Default response class and serialization advice (performance.md)
render_mode	json | html-htmx | both	json	Whether routes return JSON models or rendered templates, and which validation-error path is generated (templates.md)

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied:

• Tooling: package and env manager (pip, uv, poetry), linter and formatter, migration tool, load generator — affects every command block shown alongside code
• Conventions: router and module naming, schema suffixes (Create/Read/Update), URL casing, versioning scheme, docstring style — affects generated routers and models (structure.md)
• Platform: cloud, reverse proxy, Python version, CPU count, managed database — affects worker maths, proxy headers, and pool sizing (deployment.md)
• Safety posture: how loudly to flag missing auth, unbounded uploads, absent timeouts, verify=False, secrets in logs — affects review comments, never the correctness rules
• Integrations: cache, broker, and object store of choice (Redis, RabbitMQ, S3-compatible), auth provider, error tracker — affects which client patterns appear
• Output format: whole file vs minimal diff, how much explanation, whether tests and migrations accompany every change
• Work order: contract-first (OpenAPI or schema before handlers) vs code-first, migration before or after model change, review gates before edits — affects sequence, never correctness
• Dependencies: banned or mandated libraries (httpx vs requests, SQLModel vs SQLAlchemy, ORM vs raw SQL), tolerance for new transitive dependencies

Traps

Trap	Why it fails	Do instead
requests.get() inside async def	Blocks the loop for the full round trip; under load the whole worker stalls (rule 1)	httpx.AsyncClient from lifespan, or make the endpoint def (async.md)
@app.on_event("startup")	Deprecated in favour of lifespan, and gives no way to hold a resource open across the app's life	lifespan async context manager (structure.md)
Module-level cache = {} as an application cache	One copy per worker: hit rate divided by the worker count, invalidation reaching only one process (rule 6)	Redis, or accept per-process caching explicitly (performance.md)
app.include_router(..., dependencies=[Depends(auth)]) on everything	Health and metrics start returning 401, the orchestrator declares the pod dead and restarts it in a loop	Auth on business routers only; probes on an unauthenticated router (observability.md)
items: list = [] "shared across requests"	Pydantic deep-copies mutable defaults per instance — this is not the bug; the real need for default_factory is a computed default (uuid4, datetime.now)	Field(default_factory=...) only when the value must be computed (pydantic.md)
Optional[str] and expecting it to be optional	In pydantic v2 that is required-and-nullable; the client must send null	Give it a default: = None (pydantic.md)
Reading await request.body() in middleware, then calling the endpoint	The receive channel is exhausted; the endpoint waits for a body that will never arrive	Pure ASGI middleware that replays the stream, or read the body only in the endpoint (middleware.md)
BackgroundTasks for anything that matters	Runs in the worker after the response; a deploy or crash loses it silently, and the client already got a 200	Queue with retries and visibility (background.md)
uvicorn --reload --workers 4	--reload forces a single process; the worker count is silently ignored, so dev and prod differ in concurrency	Reload in dev, workers in prod, never both (deployment.md)
TestClient for testing async behavior	Drives the app through a sync portal — real concurrency bugs, cancellation, and loop blocking never show up	httpx.AsyncClient with ASGITransport (testing.md)
Returning the ORM object and hoping	Lazy attributes load during serialization, outside the session, after it closed	Load eagerly, convert with a response model (database.md)
Secrets in HTTPException(detail=...)	Whatever is in detail is JSON in the client's hands, including upstream error payloads	Generic message out, full context to the log with a correlation id (errors.md)

Where Experts Disagree

• Async everywhere vs honest def endpoints. One school makes every endpoint async def for uniformity; the other declares def whenever the body blocks. Boundary: an all-await stack (async driver, httpx, async cache) → async def; a single blocking library in the chain → def is strictly safer, because the threadpool bounds the damage to 40 slots instead of stopping the loop.
• ORM vs raw SQL vs SQLModel. SQLAlchemy gives migrations, identity map, and eager-loading control; raw SQL gives exact queries and no lazy-load surprises; SQLModel merges model and schema at the cost of coupling the table to the API contract. Boundary: one shape of data serving one API → SQLModel is fine; separate read and write shapes, or a schema older than the API → SQLAlchemy plus explicit response models.
• Service layer or routers that talk to the database. A repository/service layer pays off when the same operation is called from HTTP, a worker, and a CLI; below that it is indirection. Boundary: the second caller of the same logic, not the first.
• Bare bodies vs an error envelope. HTTP status plus a bare body is idiomatic and what generated clients expect; an envelope ({"data": ..., "error": ...}) survives clients that only read 200s. Boundary: public API or generated SDKs → bare with RFC 9457 problem details; a single front end with a legacy error contract → envelope, declared once in error_envelope and applied everywhere.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/fastapi (install if the user confirms):

• py — the Python language itself: packaging, typing, async primitives, tests
• pg — PostgreSQL behind the API: query plans, indexes, connection limits
• auth — authentication design across sessions, JWT, OAuth, MFA
• api-design — resource modelling, versioning, and the cost of breaking changes
• docker — containerizing and running the service

Feedback

• If useful, star it: https://clawic.com/skills/fastapi
• Latest version: https://clawic.com/skills/fastapi

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/fastapi.