Guides › HTML / PHP sites › Site down or error screens

Django: Gunicorn Workers Timing Out

Workers.

Reference guide. This guide is written from established practice and the official documentation of the tools involved. We have not yet tested every step on a live demo site. Back up your site before you change anything.
Site down or error page

Gunicorn kills a worker that does not answer in time and logs WORKER TIMEOUT. The default is 30 seconds, so slow views and heavy tasks trigger it.

1Read the log2Find the slow code3Raise the timeout4Adjust workers5Move heavy work out6Check the proxy7Restart and monitorFixed? Test the site. If not, get help.
The steps in order. Work down the list and stop when the problem is solved.

Step 1: Read the log

Illustration for Step 1: Read the log

Look for WORKER TIMEOUT and Booting worker lines to see which requests time out.

Step 2: Find the slow code

Illustration for Step 2: Find the slow code

Check the view for slow queries, external API calls or large file work.

Step 3: Raise the timeout

Illustration for Step 3: Raise the timeout

Start Gunicorn with --timeout 120 for legitimately long requests.

Step 4: Adjust workers

Illustration for Step 4: Adjust workers

A common start is 2 x CPU cores + 1. Too few workers queue requests, too many exhaust memory.

Step 5: Move heavy work out

Illustration for Step 5: Move heavy work out

Use a task queue such as Celery for emails, reports and imports.

Step 6: Check the proxy

Illustration for Step 6: Check the proxy

Nginx proxy_read_timeout should be at least the Gunicorn timeout.

Step 7: Restart and monitor

Illustration for Step 7: Restart and monitor

Restart the service and watch memory and response times.

Still stuck?

If these steps do not solve it, we fix it for you for a flat $99. Full refund if we do not solve it within 7 days.

Related guides

Did this solve it? If not, email hello@sitefixlab.org with the exact error text and we will look into it. Try the problem finder.

Last updated 2026-11-22.