Gunicorn worker timeout — how to fix

TL;DR

Gunicorn's [CRITICAL] WORKER TIMEOUT message means a worker process did not respond to the arbiter within the configured timeout (default 30 seconds). The arbiter kills and replaces the worker, causing a 502 for any in-flight request.

Common causes

• A view or API endpoint performing a long-running synchronous operation (large query, external API call)
• CPU-bound processing blocking the worker (PDF generation, image processing)
• Database connection pool exhaustion — workers waiting for a connection that never arrives
• The application stuck in a deadlock or infinite loop

Immediate fix

Increase the timeout as a temporary measure:

gunicorn myapp.wsgi:application --timeout 120 --workers 4

In your Gunicorn config file:

# gunicorn.conf.py
timeout = 120
graceful_timeout = 30
workers = 4
worker_class = 'gthread'
threads = 4

Diagnosis

Identify which requests are slow:

awk '{print $NF}' /var/log/gunicorn/access.log | sort -n | tail -20

If database queries are the bottleneck:

-- PostgreSQL: find long-running queries
SELECT pid, now() - query_start AS duration, query
FROM pg_stat_activity
WHERE state = 'active'
ORDER BY duration DESC
LIMIT 5;

Long-term fix

• Move slow work to a Celery task queue — return a 202 and process asynchronously
• Switch to an async worker class (uvicorn.workers.UvicornWorker) for I/O-bound workloads
• Add database query timeouts: statement_timeout in PostgreSQL, CONN_MAX_AGE in Django settings
• Configure connection pooling with PgBouncer for high-concurrency applications

Where Reflex helps

Reflex tracks Gunicorn worker lifecycle events and request latency distributions. When worker timeouts spike, Reflex can scale worker count, restart the Gunicorn master process, and correlate the event with recent deploys or database slowdowns to pinpoint the root cause. See How it works.