504 Gateway Timeout - What It Means & How to Fix

# Quick Definition

The server acting as a gateway or proxy did not receive a timely response from the upstream server it needed to access in order to complete the request. Simply put, the middleman server waited too long for the backend to respond and gave up.

# When Does a 504 Error Occur?

A 504 Gateway Timeout error occurs when a reverse proxy or load balancer's timeout expires before the upstream server finishes processing a long-running request. The proxy has a configured maximum wait time, and if the backend doesn't respond within that window, the proxy returns a 504 to the client.

This is different from a 502: with a 502, the upstream sent a bad response. With a 504, the upstream sent no response at all within the allowed time. The operation may still be running on the backend -- it just took too long for the proxy's patience.

# Common Causes

Upstream server processing a slow or complex database query
Database query taking too long (missing indexes, full table scans, lock contention)
API call to a third-party service timing out
Proxy timeout set too low for the operation (default Nginx timeout is 60s)
Network latency between proxy and upstream server
Upstream server under heavy load, processing requests too slowly
DNS resolution delays between internal services
Large file uploads exceeding the configured timeout window

# How to Fix a 504 Error

Identify the slow upstream request -- Check application logs and slow query logs to find which specific operation is timing out. Use APM tools for detailed tracing.
Optimize slow database queries -- Add indexes, analyze EXPLAIN plans, avoid SELECT *, and break complex queries into smaller ones. This is the most common root cause.
Increase proxy timeout values -- Set proxy_read_timeout 300s in Nginx configuration. Only do this after optimizing -- increasing timeouts masks the real problem.
Implement async processing -- For long-running tasks (report generation, data exports), use a job queue (Redis, RabbitMQ) and return a 202 Accepted with a status check endpoint.
Add request queuing -- Use a message queue for heavy operations so the proxy gets an immediate response while the work happens in the background.
Check network latency between servers -- Use ping and traceroute to identify network bottlenecks between your proxy and upstream servers.
Scale up upstream server resources -- Add more CPU, RAM, or worker processes to the backend server so it can process requests faster.
Set up proper keep-alive connections -- Enable persistent connections between proxy and upstream to avoid TCP connection overhead on every request.

# HTTP Example

Request

GET /api/reports/annual HTTP/1.1
Host: example.com
Accept: application/json

Response

HTTP/1.1 504 Gateway Timeout
Content-Type: text/html
Server: nginx/1.24.0
Date: Thu, 20 Feb 2026 12:00:00 GMT

<html>
<head><title>504 Gateway Time-out</title></head>
<body><center><h1>504 Gateway Time-out</h1></center></body>
</html>

# Related Status Codes

# Frequently Asked Questions

What's the difference between 502 and 504? +

A 502 Bad Gateway means the proxy received an invalid response from the upstream server -- the upstream replied, but with garbage or malformed data. A 504 Gateway Timeout means the proxy received no response at all within the timeout period -- the upstream simply took too long. In short: 502 = bad response received, 504 = no response in time.

How do I fix timeout errors? +

Fix timeout errors by optimizing the slow operation first: add database indexes, optimize queries, or cache expensive computations. If the operation genuinely takes a long time, increase proxy timeout values (proxy_read_timeout in Nginx) or switch to async processing with a job queue. For large file uploads, increase both client and proxy timeouts.

Can caching prevent 504 errors? +

Yes, caching can significantly reduce 504 errors. By caching responses at the CDN, proxy, or application level, you reduce the number of requests that hit the upstream server. This means less load on the backend, faster response times, and fewer timeouts. Implement cache headers (Cache-Control, ETag) and use tools like Redis or Varnish for server-side caching.

Gateway Timeout