Lorixen.
EN

Gunicorn 'WORKER TIMEOUT' errors: causes and the right settings

Short answer: [CRITICAL] WORKER TIMEOUT means Gunicorn killed a worker that went silent for longer than its timeout, 30 seconds by default, usually because a request was stuck on something slow: an external API, a heavy database query, a big export or a file upload over a slow connection. With the default "sync" workers, each worker handles one request at a time, so a few slow requests can tie up every worker and other visitors get 502s. Fix the slow request first (move long jobs to a background queue, add timeouts to outbound calls), size workers sensibly, and consider threaded or async workers if your app spends most of its time waiting.

What the timeout actually is

Gunicorn runs a master (arbiter) process that manages a pool of worker processes. Its settings documentation describes timeout as: workers silent for more than this many seconds are killed and restarted. The master watches a heartbeat from each worker; idle workers keep updating it while waiting for requests.

For the default sync workers, a worker handling one long request can't update its heartbeat, so a request that takes longer than the timeout gets the worker killed mid-request. The visitor sees an error, usually a 502 from nginx, and the log shows WORKER TIMEOUT.

The docs say the default of 30 seconds should generally suffice, and to only set it noticeably higher for sync workers if you're sure of the consequences. For other worker types, the timeout means the worker process is still communicating, rather than limiting how long one request can take.

Step 1: find the slow requests

Before changing any setting, find what's slow:

  • Match the timestamps of WORKER TIMEOUT lines with your nginx access log to see which URLs were in flight.
  • Check your app's logging or performance monitoring for requests near or above 30 seconds.
  • Look for patterns: exports, report pages, image processing, calls to payment or shipping APIs, admin bulk actions.

Usual culprits:

  • Outbound calls with no timeout. A Python HTTP call without a timeout can wait a very long time if the other side hangs. Always set one.
  • Heavy work in the request. Generating PDFs, sending hundreds of emails, resizing many images.
  • Slow database queries that need an index or a rewrite.
  • Slow clients uploading large files directly to sync workers without a buffering proxy in front.

Step 2: move long work out of requests

The dependable fix for anything that takes more than a few seconds is a background job: the request queues the task and returns immediately, a worker process does it, and the user is notified or the page polls for the result. Gunicorn's newer versions also document a separate "dirty" worker pool for long-running blocking operations like model inference, with its own longer timeout, which is worth knowing about if that fits your app.

Step 3: size your workers

Gunicorn's design notes advise against over-scaling: workers aren't the same as clients, and it typically needs only a handful (the docs say 4–12) to handle heavy traffic. The suggested starting point is:

workers = (2 × CPU cores) + 1

then adjust under real load. Each worker is a separate process with its own memory, so check that your server has enough RAM for all of them plus the database and anything else on the box. Too many workers on a small server leads to swapping, which makes everything slower.

Step 4: pick the right worker type

The design page compares worker types:

  • sync (default): one request per worker, simple and predictable, no keep-alive, and it needs a buffering proxy such as nginx in front. Good for apps that do quick work per request.
  • gthread: a pool of threads in each worker, supports keep-alive. A good middle ground for apps that spend time waiting on databases or APIs. For example: -k gthread --workers 4 --threads 4.
  • ASGI workers (such as Uvicorn's): for async frameworks like FastAPI and Starlette.
  • gevent: greenlet-based, for many concurrent connections, WebSockets and streaming, but some libraries need patches.

The docs recommend async workers for long blocking calls, direct internet traffic without a buffering proxy, streaming, long polling and WebSockets.

Step 5: recycle workers to contain memory growth

If memory creeps up over time, max_requests restarts each worker after a set number of requests, which Gunicorn's docs describe as a simple way to limit damage from memory leaks. Add max_requests_jitter so workers don't all restart at once. It's a safety net, not a substitute for finding the leak.

Keep the layers consistent

nginx and Gunicorn each have timeouts. If nginx gives up first, users get a 504 while Gunicorn keeps working; if Gunicorn kills the worker first, users get a 502. Decide which layer should end slow requests and set the others slightly higher, and make sure the app's own outbound timeouts are shorter than both.

A worked example

An illustrative Ottawa event ticketing site saw WORKER TIMEOUT and 502s every time a promoter downloaded a full attendee export. Logs showed the export took about a minute, and with four sync workers, two concurrent exports plus normal traffic left buyers waiting. The developer moved exports to a background job that emails a download link, added timeouts to the payment provider calls, and switched to gthread workers with a modest thread count. Timeouts stopped, and checkout stayed responsive during exports.

FAQ

Should I just raise the timeout to 120 seconds?

Only as a short-term patch. With sync workers it means slow requests hold workers even longer.

Why do I get 502s without WORKER TIMEOUT in the logs?

Check for workers crashing from memory limits, nginx timeouts, or Gunicorn not running at all.

Does --preload help?

It loads the app before forking, saving memory and startup time, but doesn't fix slow requests.

How do I know if threads are safe for my app?

Most modern Django and Flask apps are fine with threads; avoid shared mutable globals.

If your Python app is throwing timeouts or 502s under load, send us your Gunicorn and nginx settings and we'll help you find the bottleneck.

Sources

WhatsAppBook a call