Introduction

A Gunicorn CRITICAL WORKER TIMEOUT means a worker stopped responding within Gunicorn’s configured timeout window. On AWS, that often shows up behind another layer such as ALB, NLB, or NGINX, but the Gunicorn message still points to the same core issue: a worker is blocked, overloaded, or taking too long to finish the request. Increasing the timeout sometimes hides the symptom, but it does not fix the cause.

What the Timeout Actually Means

Gunicorn expects each worker to stay healthy and responsive. If a worker does not complete work or check in within the configured timeout, Gunicorn kills it and starts a replacement.

A simple configuration example:

1bind = "0.0.0.0:8000"
2workers = 4
3timeout = 60
4graceful_timeout = 30

If a request handler blocks longer than timeout, the worker is treated as stuck. That can happen because of CPU-heavy work, slow database calls, external APIs, deadlocks, or an exhausted server.

AWS Usually Adds Another Timeout Layer

If Gunicorn is deployed behind an AWS load balancer, there is often also an idle timeout on the load balancer side. That means you now have at least two different timeout systems:

• Gunicorn worker timeout
• load balancer connection or idle timeout

If the load balancer times out earlier, the client may see a dropped request even before Gunicorn decides the worker is unhealthy. If Gunicorn times out earlier, the worker restarts and the request fails from the application side first.

That is why debugging must include both Gunicorn and AWS configuration.

Find Out Why the Worker Is Stuck

Start with logs and request profiling, not with bigger timeout numbers.

gunicorn app:app --workers 4 --timeout 60 --access-logfile - --error-logfile -

Look for patterns such as:

• one endpoint always timing out
• timeouts only during high load
• database queries that spike in latency
• requests waiting on S3, another API, or a slow network hop

On AWS, also check CPU, memory, and disk pressure in CloudWatch. A worker that times out under resource starvation needs a different fix than a worker blocked on a bad SQL query.

Common Causes and Matching Fixes

If the app is CPU-bound, moving that work off the request path is often the best answer. A long report, image conversion, or ML inference job usually belongs in a background queue.

If the app is I/O-bound, async workers or better dependency timeouts may help. For example, if many requests wait on slow external services, synchronous workers can get pinned unnecessarily.

For basic synchronous Flask or Django apps, keep the app servers focused on request-response work and push long-running tasks to Celery, SQS-backed workers, or another job system.

Adjust Timeouts Only After You Understand the Workload

Sometimes a request genuinely needs more than the default 30 seconds, and increasing the timeout is reasonable.

gunicorn app:app --workers 4 --timeout 120

But this should follow diagnosis, not replace it. If requests are slow because of an N+1 query, increasing the timeout merely makes users wait longer before the same bad code path completes.

Also keep the timeout chain consistent. If Gunicorn is set to 120 seconds but the ALB idle timeout is lower, the client still loses.

Worker Type Matters

Gunicorn has different worker classes. A synchronous worker is simple, but it can be a bad fit for I/O-heavy applications.

gunicorn app:app --worker-class gevent --workers 4 --timeout 60

This is not a universal fix, but if the application spends most of its time waiting on network I/O, the worker model matters. If the workload is CPU-bound, changing the worker class will help much less than changing the architecture.

Common Pitfalls

• Increasing the Gunicorn timeout without investigating what the worker is waiting on.
• Forgetting that AWS load balancers may have their own timeout behavior.
• Running CPU-heavy or report-generation work directly in the web request path.
• Choosing an inappropriate worker class for an I/O-heavy application.
• Looking only at Gunicorn logs and ignoring system metrics such as CPU, memory, and DB latency.

Summary

• A Gunicorn worker timeout means the worker stopped responding within the allowed window.
• On AWS, the effective request behavior may also be shaped by load-balancer timeouts.
• Diagnose the blocked or slow work first before increasing timeout values.
• Move long-running jobs off the request path when possible.
• Tune worker class, resource sizing, and timeout values only after the actual bottleneck is understood.