FastAPI Fix, Crash & Optimization Guide

FastAPI is a modern Python web framework for building APIs with Python type hints, built on Starlette and Pydantic. It delivers automatic OpenAPI docs, data validation, and async support, and runs on an ASGI server such as Uvicorn.

Install / First Setup

Install the framework and an ASGI server:

pip install fastapi uvicorn

# main.py
from fastapi import FastAPI
app = FastAPI()

@app.get("/")
def read_root():
    return {"hello": "world"}

Run the dev server:

uvicorn main:app --reload

This serves at http://127.0.0.1:8000 with interactive docs at /docs. Use a virtual environment (python -m venv .venv) to isolate packages. FastAPI requires Python 3.8+ (verify against your installed version).

Common Issues & Fixes

"Address already in use" (port 8000)

Cause: Another Uvicorn/process holds the default port. Fix: Run on another port: uvicorn main:app --reload --port 8001.

"No module named 'fastapi'" / 'uvicorn'

Cause: Packages aren't installed in the active interpreter, or the venv isn't activated. Fix: Activate your venv and pip install fastapi uvicorn. Confirm the interpreter matches your editor.

422 Unprocessable Entity on requests

Cause: The request body/query doesn't match the Pydantic model (wrong types, missing required fields). Fix: Check the field names and types against your model; FastAPI returns the exact validation error body. Use Optional/default for optional fields and Field(...) for required ones.

CORS blocked in the browser

Cause: The browser blocks cross-origin requests because no CORS policy is configured. Fix: Add the middleware:

from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Reload not picking up changes

Cause: The import string (main:app) doesn't resolve, or you edited a file outside the watched tree. Fix: Ensure main is the module and app the FastAPI instance, and run uvicorn from the project root. --reload watches the current directory.

Performance & Optimization

• Low-End (4–8 GB RAM): Dev with uvicorn main:app --reload (single worker) locally. Keep the app modular; avoid heavy sync blocking calls in the event loop.
• Mid (16 GB): For production use multiple workers: uvicorn main:app --workers 4 (≈ CPU cores), or run behind Gunicorn with Uvicorn workers (gunicorn -k uvicorn.workers.UvicornWorker main:app -w 4). Use async async def routes for I/O-bound work.
• Workstation (32 GB+): Scale workers across cores, place a reverse proxy (Nginx) in front, and use a connection pool for the database. Offload static/files and add response caching where safe.

Use Pydantic v2 models (faster validation), keep request bodies small, and prefer async only for genuinely I/O-bound operations; CPU-bound work should go to a worker/threadpool.

Version & Compatibility Notes

• FastAPI requires Python 3.8+ (exact minimum depends on the installed version); Pydantic v2 is used by current releases with some behavioral differences from v1.
• The dev server is Uvicorn with --reload; production should use multiple Uvicorn workers or Gunicorn+Uvicorn workers, never the single-process reload server.
• For exact version/Python requirements, consult official release notes.

FAQ

Q: How do I change the FastAPI port? A: uvicorn main:app --port 8001 (default is 8000). Use --host 0.0.0.0 to expose it.

Q: Why do I get 422 validation errors? A: The request didn't match your Pydantic model — wrong field names, missing required fields, or wrong types. The response body lists the exact failures.

Q: How do I enable CORS? A: Add CORSMiddleware with allow_origins set to your frontend origin(s). Avoid "*" with credentials.

Q: How do I run FastAPI in production? A: Use uvicorn main:app --workers N or Gunicorn with Uvicorn workers behind a reverse proxy. Don't use --reload in production.

Q: What's the difference between sync and async routes? A: async def routes run on the event loop for I/O concurrency; def routes run in a threadpool. Use async for I/O-bound work and keep CPU-heavy code synchronous/offloaded.

Q: Where are the API docs? A: Interactive docs are at /docs (Swagger UI) and /redoc (ReDoc) by default.

Related Guides

• Flask Fix & Optimization Guide
• Django Fix & Optimization Guide
• Dev RAM Calculator

Accuracy Note

Commands and paths reflect common, real-world setups as of 2026-08. Always verify against your installed version and OS. When in doubt, consult the official FastAPI documentation.