FastAPI 502 behind nginx — complete fix

TL;DR

A 502 Bad Gateway from nginx in front of FastAPI means nginx could not get a valid response from the Uvicorn backend. The Uvicorn process is either down, overloaded, or misconfigured.

Common causes

• Uvicorn process has crashed or is not running
• nginx is proxying to the wrong address or port
• Socket file permissions are incorrect (when using Unix sockets)
• Uvicorn workers are all busy and the connection backlog is full
• Timeout mismatch — Uvicorn takes longer than nginx's proxy_read_timeout

Diagnosis

Check if Uvicorn is running:

systemctl status fastapi-app
ss -tlnp | grep :8000

Check nginx error log:

tail -50 /var/log/nginx/error.log

Look for connect() failed (111: Connection refused) or upstream timed out.

Fix the nginx configuration

TCP proxy setup:

upstream fastapi {
    server 127.0.0.1:8000;
    keepalive 32;
}

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://fastapi;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 60s;
        proxy_connect_timeout 10s;
    }
}

Unix socket alternative (lower overhead on the same host):

uvicorn main:app --uds /run/uvicorn.sock --workers 4

upstream fastapi {
    server unix:/run/uvicorn.sock;
}

Ensure the socket has correct ownership:

chown www-data:www-data /run/uvicorn.sock

Timeout alignment

Match timeouts across the stack: nginx proxy_read_timeout should exceed Uvicorn's timeout-keep-alive (default 5s) and be longer than your slowest expected response. For CPU-heavy endpoints, use background tasks rather than blocking the response.

Where Reflex helps

Reflex monitors nginx upstream error rates and Uvicorn process health in tandem. When 502s appear, it can automatically restart Uvicorn, verify the upstream is healthy, and alert your team with correlated logs from both nginx and the application layer. See How it works.