Gunicorn '[CRITICAL] WORKER TIMEOUT (pid: N)' and workers restarting (502s from nginx) for Django or Flask apps. How do I fix worker timeouts properly?

Cause: Gunicorn's master process kills and restarts any worker that stays silent longer than the timeout setting (default 30 seconds). With the default sync worker, each worker handles one request at a time, so a single request that takes longer than 30 seconds (slow database query, external API call, large file processing, a request stuck waiting on a lock) gets its worker killed, which shows up as WORKER TIMEOUT in the logs and 502/504 responses at the proxy. It also happens when all workers are busy and the machine is overloaded, or when a worker is starved of CPU or memory (containers with tight limits). Fix (best first): 1. Find what's slow: log request durations, and check the app's own logs and database for the requests that time out. Fixing the slow path (indexes, caching, timeouts on outbound HTTP calls) is the real fix. 2. Move long work out of the request: run it in a background job (Celery, RQ, a task queue) and return quickly. 3. Size workers for the workload: Gunicorn suggests about 2-4 workers per CPU core as a starting point (workers setting or the WEB_CONCURRENCY variable), and gthread workers with threads > 1 for I/O-bound apps; async workers (e.g. gevent) suit many concurrent slow I/O calls. 4. Raise timeout only for genuinely long requests you can't move (e.g. --timeout 120), and keep the reverse proxy's timeouts consistent; very high values hide problems and tie up sync workers. 5. In containers, give enough CPU and memory; memory pressure and OOM kills can look like timeouts. Check dmesg or the container's exit reason. Verify: the logs show no new WORKER TIMEOUT entries under normal load, and the slow endpoint completes within the timeout (or runs in the background). Sources: https://gunicorn.org/reference/settings/ https://gunicorn.org/design/