How to Fix 504 Gateway Timeout in Nginx on Ubuntu

A 504 Gateway Timeout in Nginx means a gateway did not receive a timely response from an upstream server. On an Ubuntu VPS, that upstream might be a Node.js application, a Python service, or PHP-FPM. The fastest route to a lasting fix is to identify which hop timed out, inspect the application, and adjust timeouts only when the workload justifies it.

This guide walks through diagnosis for a server you administer. Commands use common Ubuntu paths; replace the domain, service name, port, and PHP version with your own values.

Quick checklist: where to start

1. Record the failing URL, time, and whether every request or only one endpoint fails.
2. Check the Nginx error log for the upstream address and timeout phase.
3. Test the upstream directly from the VPS.
4. Check application logs, worker availability, database delays, and server resources.
5. Apply a targeted fix, validate the configuration, and retest the original request.

504 vs 502: choose the right troubleshooting path

A 504 points to a response that did not arrive within a gateway's waiting period. A 502 indicates an invalid upstream response and may also appear when a connection is refused or a worker exits unexpectedly. The status alone does not identify the failing component: a CDN, load balancer, Nginx, or another proxy can generate it.

If your log shows connection refused rather than a timeout, start with our guide to fixing 502 Bad Gateway in Nginx on Ubuntu.

1. Find the timeout in the Nginx error log

sudo tail -n 100 /var/log/nginx/error.log
sudo journalctl -u nginx --since "30 minutes ago" --no-pager

Your site may use a separate error log. Match the timestamp and request path to the incident. A message containing upstream timed out usually includes the upstream address and whether Nginx was connecting, sending a request, or reading a response header.

• While connecting: investigate the upstream address, routing, firewall rules, and whether the service accepts connections.
• While reading a response header: investigate application processing, blocked workers, slow queries, and external API calls.
• While sending a request: investigate whether the upstream is accepting request data promptly.

Check the access log too. If no matching request reaches your origin, investigate the proxy or CDN in front of the VPS. Avoid posting raw logs publicly; URLs and headers can contain private values.

2. Test the application without the public proxy

For an HTTP application listening on port 3000, run these checks on the VPS. Replace the example path with the failing read-only endpoint and include the correct Host header if your application requires it.

sudo ss -ltnp
curl -sS -o /dev/null --max-time 15 -H 'Host: example.com' -w 'HTTP %{http_code} total %{time_total}s\n' http://127.0.0.1:3000/
sudo systemctl status your-app.service --no-pager
sudo journalctl -u your-app.service --since "30 minutes ago" --no-pager

A fast homepage does not prove that a slow report or checkout route is healthy. Test the affected endpoint carefully without repeating a payment or other write operation. A direct request that also stalls points toward the application or its dependencies. A fast direct response suggests checking the Nginx route, upstream selection, and any additional proxy layer.

PHP-FPM uses FastCGI, so an ordinary HTTP curl request cannot test its socket directly. Check the FPM service and logs instead, and confirm that the configured socket matches the running PHP version.

3. Check resource pressure and blocked workers

uptime
free -h
df -h
df -i
top

Compare these readings with your normal workload. Look for sustained CPU pressure, low available memory, disk exhaustion, and applications waiting on storage or network calls. Review application errors around the same time, including database connection waits and slow queries.

For PHP-FPM, check for worker-pool saturation and slow requests before raising the worker limit. More workers consume more memory. For Node.js, CPU-heavy synchronous work can delay other requests; for Python, busy workers can queue requests behind long tasks.

When storage is the bottleneck, follow our Ubuntu VPS disk-space troubleshooting guide. If database connections are exhausted, review PostgreSQL connection pooling and monitoring.

4. Use the correct Nginx timeout directive

For HTTP upstreams configured with proxy_pass, Nginx uses proxy_connect_timeout for establishing a connection, proxy_send_timeout while sending request data, and proxy_read_timeout while waiting for response data. Read and send timeouts measure gaps between successive operations; they are not total request-duration limits. See the official Nginx proxy timeout documentation.

If an endpoint legitimately needs more time, add a bounded setting to its existing location. For example, a report route using an HTTP upstream could use:

# Inside the existing location that handles the report:
proxy_read_timeout 120s;

The 120-second value is an example, not a universal recommendation. Keep the existing proxy destination, headers, and authentication rules. Do not add a competing location without understanding your current routing.

For PHP requests passed through fastcgi_pass, the corresponding response setting is fastcgi_read_timeout:

# Inside the existing PHP/FastCGI location, when justified:
fastcgi_read_timeout 120s;

Its read timeout also applies between read operations. Consult the official FastCGI documentation. Application, PHP-FPM, CDN, and load-balancer limits may still terminate the request sooner. Align those limits deliberately rather than raising everything.

5. Validate, reload, and verify the fix

Save a copy of the configuration before editing. If a hosting control panel manages Nginx, use its supported configuration mechanism so a later update does not overwrite the change.

sudo nginx -t
# Run the reload only if the configuration test succeeds:
sudo systemctl reload nginx

Retest the original URL through the public domain and watch the error log. Confirm both the returned status and a sensible response time. Test another route as well to catch accidental routing changes. If the fix increases waiting time without reducing application delays, return to the upstream diagnosis.

Prevent recurring gateway timeouts

Set deadlines on external API requests, investigate slow database queries, and monitor latency alongside error rates. Move lengthy exports, image processing, and batch jobs into background workers where appropriate. A web request can return a job identifier while the client checks progress.

For Laravel workloads, our queues and scheduler production checklist covers related deployment concerns. For broader infrastructure planning, read how to remove VPS single points of failure.

Frequently asked questions

Will restarting Nginx fix a 504 Gateway Timeout?

It may change symptoms temporarily, but it does not resolve a slow application, blocked database query, or unreachable upstream. Capture logs first and fix the component causing the delay.

Should I increase proxy_read_timeout to fix every 504?

No. Extend it only for requests whose expected work justifies the extra waiting time. A longer timeout can keep connections and workers occupied while the underlying bottleneck remains.

Why does only one page time out?

That route may perform a costly query, call a slow third-party API, or generate a large report. Compare its application logs and dependency timings with a healthy endpoint.

Can a CDN return 504 when Nginx is working?

Yes. An outer gateway has its own waiting period. Compare origin logs with the public response to find the failing hop; increasing an origin timeout does not automatically change a CDN's limit.

Keep diagnosis tied to evidence

A reliable Nginx 504 fix starts with the failing request and follows it through each upstream dependency. Use logs to locate the delay, correct the bottleneck, and verify the same request afterward. Explore the Core Panel website and our hosting tutorials for more practical VPS operations guidance.