Common Nginx Error Log Pattern (Python / FastAPI)
When upstream sockets, timeouts, body limits, or Docker DNS rules are misconfigured for Python / FastAPI, Nginx typically records an entry matching the log line below inside /var/log/nginx/error.log:
2026/11/22 15:09:44 [error] 2210#2210: *408 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 198.51.100.14, server: api.example.com, request: "POST /api/v1/embeddings HTTP/2.0", upstream: "http://127.0.0.1:8000/api/v1/embeddings", host: "api.example.com"
Reverse Proxy Architecture & Header Forwarding for Python / FastAPI
FastAPI powered by Uvicorn (or Gunicorn with UvicornWorker processes) is intentionally designed to run behind a battle-tested reverse proxy like Nginx in production. While Uvicorn excels at asynchronous ASGI concurrency, Nginx handles TLS termination, HTTP/2 multiplexing, slow-client buffering, request size limits, and graceful reloads without starving Python worker processes.
Two FastAPI-specific behaviors frequently break behind an unconfigured Nginx proxy: Swagger UI (/docs) subpath resolution and HTTP-to-HTTPS scheme awareness. When Nginx terminates HTTPS on port 443 and forwards plain HTTP to 127.0.0.1:8000, FastAPI generates redirect URLs (such as 307 trailing-slash redirects or OAuth callback links) starting with http:// instead of https:// unless Uvicorn is launched with --proxy-headers and --forwarded-allow-ips and Nginx sends X-Forwarded-Proto $scheme.
If you mount FastAPI under a subpath such as /api/ using Strip Prefix (proxy_pass http://127.0.0.1:8000/;), Swagger UI at /api/docs attempts to download /openapi.json from the domain root instead of /api/openapi.json, returning HTTP 404, unless you also pass --root-path /api (or root_path="/api" in FastAPI()). Furthermore, ML inference, PDF generation, and LLM streaming routes regularly exceed Nginx's default 60-second proxy_read_timeout, throwing 504 Gateway Timeout even while Uvicorn finishes computing cleanly.
Validating your Nginx configuration alongside Uvicorn startup flags prevents silent IP spoofing in rate limiters (where request.client.host reports 127.0.0.1 for every user), ensures multipart file uploads up to 50 MB do not fail with 413 Request Entity Too Large, and keeps WebSocket and Server-Sent Events endpoints responsive under heavy concurrent traffic.
When scaling FastAPI behind Nginx in high-throughput production workloads, tune proxy_connect_timeout, keepalive connections, and client_max_body_size carefully to match your largest file upload or batch embedding endpoint. Monitoring Nginx $upstream_response_time alongside FastAPI structured logs immediately distinguishes slow Python database or vector queries from network saturation. Always verify that /docs, /redoc, and /openapi.json respect your root_path setting; or restrict /docs by internal IP allowlists in Nginx when deploying private B2B FastAPI microservices.
Step-by-Step Nginx & Python / FastAPI Deployment Guide
Apply the Nginx server block above alongside these upstream framework trust-proxy settings so HTTPS detection, real client IPs, and reload safety work reliably in production.
1Launch Uvicorn/Gunicorn With --proxy-headers and Explicit Trusted Proxy IPs
/etc/systemd/system/fastapi.serviceUvicorn ignores X-Forwarded-For and X-Forwarded-Proto headers from Nginx unless --proxy-headers is enabled and Nginx's IP (127.0.0.1 on the same host, or your Docker bridge subnet) is listed in --forwarded-allow-ips.
/etc/systemd/system/fastapi.serviceini[Unit] Description=FastAPI Uvicorn Production Service After=network.target [Service] User=www-data WorkingDirectory=/srv/fastapi-app ExecStart=/srv/fastapi-app/.venv/bin/gunicorn app.main:app \ --workers 4 \ --worker-class uvicorn.workers.UvicornWorker \ --bind 127.0.0.1:8000 \ --forwarded-allow-ips="127.0.0.1" Restart=always [Install] WantedBy=multi-user.target2Configure FastAPI root_path When Stripping an /api/ Prefix in Nginx
app/main.pyIf Nginx routes /api/ to FastAPI with Strip Prefix enabled, configure root_path from an environment variable so OpenAPI (/api/docs) and Swagger's Try-It-Out buttons resolve /api/openapi.json accurately.
app/main.pypythonimport os from fastapi import FastAPI, Request app = FastAPI( title="Production FastAPI Service", root_path=os.getenv("FASTAPI_ROOT_PATH", ""), ) @app.get("/health") async def health(request: Request): return { "status": "ok", "scheme": request.url.scheme, "client_ip": request.client.host if request.client else None, }3Disable Nginx Buffering on FastAPI StreamingResponse / SSE Endpoints
app/routers/stream.pyRather than disabling Nginx proxy_buffering globally (which hurts regular JSON throughput), emit the X-Accel-Buffering: no response header directly from FastAPI StreamingResponse endpoints so LLM tokens flush immediately.
app/routers/stream.pypythonfrom fastapi import APIRouter from fastapi.responses import StreamingResponse router = APIRouter() async def token_generator(): for chunk in ["hello ", "from ", "fastapi"]: yield f"data: {chunk}\n\n" @router.get("/stream") async def stream_events(): return StreamingResponse( token_generator(), media_type="text/event-stream", headers={"X-Accel-Buffering": "no", "Cache-Control": "no-cache"}, )4Install Nginx Site Config, Test Syntax, and Verify Forwarded Scheme
terminalEnable your generated Nginx server block, reload without dropping active connections, and confirm /health reports scheme: https and your true remote IP.
terminalbashsudo nginx -t && sudo systemctl reload nginx curl -s https://api.example.com/health | jq .
Common Python / FastAPI Nginx Reverse Proxy Pitfalls
Review these three production failure modes before reloading Nginx on staging or live servers.
Mixed-Content Redirect Loops From Missing --proxy-headers in Uvicorn
Without --proxy-headers and --forwarded-allow-ips, Uvicorn assumes every proxied request arrived over plain HTTP. FastAPI's automatic trailing-slash redirects then emit Location: http://api.example.com/items/ instead of https://, causing browser mixed-content blocks or infinite redirect loops.
504 Gateway Timeout on Slow ML or LLM Endpoints
Nginx's default proxy_read_timeout is 60 seconds. Any synchronous FastAPI endpoint or slow upstream inference call taking 65 seconds gets terminated by Nginx with HTTP 504 even though Uvicorn is still running cleanly. Raise proxy_read_timeout to 120s–300s for heavy compute routes.
Using --forwarded-allow-ips="*" While Port 8000 Is Publicly Exposed
Setting --forwarded-allow-ips="*" tells Uvicorn to trust X-Forwarded-For from any client. If Uvicorn is bound to 0.0.0.0:8000 without firewall isolation, attackers can spoof X-Forwarded-For headers directly to bypass IP rate limiting. Always bind to 127.0.0.1 or lock down the Docker network.
Complete Your Deployment With Matching Docker Compose & CORS Tools
Pair this Nginx reverse proxy block with healthcheck-gated Docker Compose orchestration and verified browser CORS headers:
Build a production Docker Compose stack for Python FastAPI, PostgreSQL 16, Redis 7, and Celery workers with pg_isready healthchecks and Alembic migrations.
Fix CORS preflight failures between Python FastAPI (Uvicorn) and Next.js on port 3000. Configure CORSMiddleware order, trailing redirects, and credentials.
Frequently Asked Questions
- Why does FastAPI /docs show "Failed to load API definition" (404 /openapi.json) behind Nginx /api/?
- When Nginx proxies location /api/ with a trailing slash (proxy_pass http://127.0.0.1:8000/;), FastAPI sees /docs instead of /api/docs and tells Swagger UI to fetch /openapi.json at the domain root. Pass root_path="/api" to FastAPI() or --root-path /api to Uvicorn to fix it immediately.
- Should I run multiple Uvicorn workers behind Nginx?
- Yes. Run Uvicorn with --workers $(nproc) (or Gunicorn with UvicornWorker) on multi-core servers so Python utilizes every CPU core, while Nginx distributes incoming TLS connections cleanly over loopback HTTP/1.1.
- Why does request.client.host always return 127.0.0.1 in FastAPI?
- Nginx connects to Uvicorn over 127.0.0.1. Unless Nginx sets X-Forwarded-For $proxy_add_x_forwarded_for AND Uvicorn runs with --proxy-headers --forwarded-allow-ips="127.0.0.1", Uvicorn ignores the forwarded client IP header.
- Can Nginx handle both FastAPI HTTP endpoints and FastAPI WebSockets on the same port?
- Yes. Enabling WebSocket Upgrade headers (Upgrade $http_upgrade and Connection $connection_upgrade) alongside proxy_http_version 1.1 lets Nginx cleanly proxy standard REST requests and @app.websocket("/ws") connections to Uvicorn port 8000.
Related Nginx Reverse Proxy Guides
Browse all 10 Nginx guides →Nginx Reverse Proxy Config for Django + Gunicorn (SSL, Static & CSRF)
Generate a production Nginx reverse proxy for Django and Gunicorn on port 8000 with SECURE_PROXY_SSL_HEADER, CSRF_TRUSTED_ORIGINS, /static/, and /media/.
Nginx Reverse Proxy for Docker Compose Services (127.0.0.11 DNS Resolver)
Prevent 502 Bad Gateway and Nginx startup crashes in Docker Compose using resolver 127.0.0.11 and variable proxy_pass for dynamic container restarts.
Nginx Reverse Proxy Config for Socket.IO & WebSockets (Upgrade & 3600s)
Fix WebSocket 400 errors and 60-second disconnects in Nginx for Socket.IO and ws servers. Generate Upgrade, Connection map, and 3600s proxy_read_timeout blocks.
Nginx Multi-Service Subpath Routing Config (/api/, /auth/ & /ws/)
Route /api/, /auth/, and /ws/ microservices to separate backend ports under one Nginx HTTPS domain. Master trailing-slash prefix stripping and prevent 404s.