nginx "upstream timed out" (110: Connection timed out): causes and fixes

nginx returns 504 when the app behind it is too slow. How to read the upstream timed out error log, which timeout directive applies, and how to fix the cause.

· 6 min read · By the Spot Downtime team

Visitors see a 504 Gateway Time-out page. In the nginx error log you find a line like this:

[error] 1234#1234: *5678 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 203.0.113.7, server: example.com, request: "GET /report HTTP/1.1", upstream: "http://127.0.0.1:8000/report"

nginx is acting as a reverse proxy. It passed the request to your application (the upstream), waited, and gave up. The 504 is nginx telling the client it never got an answer in time. For the general picture of gateway errors see 502, 503 and 504 errors explained; this post is about the nginx side.

Read the error: which stage timed out

The text after “while” tells you where the time was lost.

  • while connecting to upstream: nginx could not open a connection. The app is down, listening on a different port or address, or a firewall drops the packets. Controlled by proxy_connect_timeout.
  • while reading response header from upstream: the connection worked but the app took too long to start answering. This is the most common case: a slow query, a stuck worker or a heavy request. Controlled by proxy_read_timeout.
  • while sending request to upstream: nginx could not send the request body fast enough. Controlled by proxy_send_timeout. Rare, and usually seen with large uploads.

If you use PHP-FPM, the same logic applies with fastcgi_connect_timeout, fastcgi_send_timeout and fastcgi_read_timeout. All of these default to 60 seconds.

Find the failing requests

# recent timeouts
grep "upstream timed out" /var/log/nginx/error.log | tail -20

# which URLs hit it most
grep "upstream timed out" /var/log/nginx/error.log \
  | grep -o 'request: "[A-Z]* [^ ]*' | sort | uniq -c | sort -rn | head

If it is always the same URL, you have a slow endpoint. If it is random URLs and starts at a specific time, the whole application is overloaded or something it depends on (database, external API) slowed down.

Fix it: cause first, timeout second

1. The upstream is not reachable

For “while connecting”, confirm the app is running and listening where nginx expects it:

ss -ltnp | grep 8000
curl -sv http://127.0.0.1:8000/ -o /dev/null

If the upstream is a hostname, remember nginx resolves it once at startup. After an IP change it keeps connecting to the old address until reload. See DNS TTL explained for how cached addresses cause this.

2. The app is slow

Time the request directly against the app, bypassing nginx, so you know whether nginx is the problem at all:

curl -s -o /dev/null -w 'connect %{time_connect}s  first byte %{time_starttransfer}s  total %{time_total}s\n' \
  http://127.0.0.1:8000/report

If the app itself takes minutes, look there: slow database queries, missing indexes, a blocking call to a third-party API, or all workers busy. Check that the number of app workers (PHP-FPM children, gunicorn workers, Node processes) matches your traffic. When every worker is occupied by a slow request, new requests queue until nginx times out.

3. The work is legitimately long

Exports, report generation and imports can take longer than a minute. Raising the timeout works but ties up connections. A better pattern is to accept the request, return immediately, process it in a background job and let the client poll for the result. If you must raise the limit, do it for one location only:

location /reports/ {
    proxy_pass http://127.0.0.1:8000;
    proxy_read_timeout 300s;
}

Check every layer

Timeouts stack. If nginx waits 300 seconds but the app server kills requests at 30 (gunicorn's default --timeout is 30 seconds, PHP has max_execution_time), or a load balancer or CDN in front of nginx gives up earlier, the shortest one wins and you will see a different error. Cloudflare, for example, ends the connection with a 524 when the origin takes too long.

After editing the config, test and reload without dropping connections:

sudo nginx -t && sudo systemctl reload nginx

When it happens only sometimes

  1. Compare the timestamps of the errors with deploys, cron jobs, backups and traffic spikes.
  2. Check CPU, memory and swap on the app server at those times. An app that swaps is an app that times out.
  3. Check the database for long-running queries and lock waits.
  4. Look at upstream keepalive settings. If nginx reuses connections that the app already closed, you can see resets rather than timeouts.

Catch it before visitors report it

Intermittent 504s are easy to miss because your own requests often work. A monitor that checks every few minutes and records the response time will show a slow trend before it turns into timeouts, and alerts you when checks start failing. Add an alert threshold on response time for the endpoints that matter, not just on up or down.

Website availability checkerCheck from outside your network whether a site is returning errors or timing out right now.

Get new guides by email

Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.

Unsubscribe from any email with one click. See our privacy policy.

Keep reading