How do I diagnose a 504 Gateway Timeout on a server?
A 504 response means a gateway did not receive a required upstream response in time. The cause may be connection establishment, a slow database query, an external API or exhausted application workers. Raising every timeout can extend user waits and increase resource pressure without resolving the underlying delay.
Before you start
- A safe request that reproduces the delay.
- The verified HTTP upstream address and relevant application logs.
Instructions
1. Match the timeout with proxy logs
Read the log entry for the failing request and distinguish connecting to upstream from waiting for response data. Check whether all routes fail or only a specific expensive action.
sudo tail -n 60 /var/log/nginx/error.logShows a bounded example log extract; use the site’s configured log path.
2. Measure a safe upstream request
Use the actual local HTTP endpoint and a bounded timeout. A health endpoint should be chosen only if it exercises the dependency you need to assess.
curl --silent --show-error --output /dev/null --connect-timeout 3 --max-time 20 --write-out 'connect=%{time_connect} first_byte=%{time_starttransfer} total=%{time_total}
' http://127.0.0.1:8080/Reports connection, first-byte and total time for this HTTP request.
3. Investigate the slow dependency
Correlate application worker utilisation, database waits and external calls at the same time. If a long request is intentional, review a route-specific timeout and the full client/proxy/application chain after measuring its normal duration.
Check the result
- The affected operation completes within its intended duration and proxy errors stop for that route.
Troubleshooting
- A local health endpoint is fast but a user action times out
- Trace the actual action and its dependencies. A shallow health response does not prove that every database query or third-party request is healthy.
Official references
Use the documentation for your installed version when a flag, service name or platform feature differs.