HTTP 504 Gateway Timeout — upstream server didn't respond in time

What causes this error

A 504 is generated by an intermediary (reverse proxy, load balancer, CDN, API gateway) when it forwarded the request to an upstream server but didn't receive a complete response within its configured timeout. The upstream server is reachable and accepted the connection (otherwise the intermediary would return 502 or 503), but the response is taking too long. Common causes: a database query scanning millions of rows without an index, an external API call to a third-party service that is slow or hanging, a file upload/processing operation that exceeds the proxy timeout, DNS resolution delays between the proxy and upstream, or the upstream event loop is blocked by synchronous computation.

How to fix it

1. 01

   step 1

   Identify which layer is generating the 504

   The 504 comes from the intermediary, not the backend. Check response headers to identify who timed out — Nginx, Cloudflare, AWS ALB, or your API gateway. This tells you which timeout to adjust.

   # Check response headers for the intermediary
   curl -sI https://example.com/slow-endpoint
   
   # Look for:
   # Server: nginx          -> Nginx proxy_read_timeout
   # Server: cloudflare     -> Cloudflare 100s timeout (not configurable on free plan)
   # Via: 1.1 ... (CloudFront) -> CloudFront origin response timeout
   # X-Amzn-ErrorType       -> API Gateway 29s hard limit

   Copy
2. 02

   step 2

   Find the slow operation on the backend

   The backend is processing something that takes longer than the proxy allows. Find what's slow — it's usually a database query, an external API call, or a file operation.

   # Check for slow queries (PostgreSQL)
   psql -c "SELECT pid, now() - query_start AS duration, 
     substring(query, 1, 100) FROM pg_stat_activity 
     WHERE state = 'active' ORDER BY duration DESC LIMIT 10;"
   
   # Check for slow queries (MySQL)
   mysql -e "SHOW PROCESSLIST;" | grep -v Sleep
   
   # Check for hanging external API calls
   netstat -an | grep ESTABLISHED | grep -c ':443'

   Copy
3. 03

   step 3

   Optimize the slow operation or increase the timeout

   If the operation can be made faster (add a database index, cache the result, paginate), do that first. If it legitimately takes 2+ minutes (report generation, large file processing), increase the proxy timeout and consider making it asynchronous.

   # Nginx — increase timeout for a specific slow endpoint
   location /api/reports {
       proxy_pass http://backend;
       proxy_read_timeout 180s;
       proxy_connect_timeout 10s;
       proxy_send_timeout 180s;
   }
   
   # AWS ALB — increase idle timeout (default 60s, max 4000s)
   aws elbv2 modify-load-balancer-attributes \
     --load-balancer-arn arn:aws:... \
     --attributes Key=idle_timeout.timeout_seconds,Value=120

   Copy
4. 04

   step 4

   Make long operations asynchronous

   For operations that genuinely take minutes (PDF generation, data exports, video processing), don't make the client wait. Accept the request, return a 202 Accepted with a job ID, and let the client poll for completion.

   // Instead of synchronous processing that triggers 504:
   // app.post('/api/export', async (req, res) => {
   //   const data = await generateLargeExport(); // takes 3 min
   //   res.json(data); // 504 before this line runs
   // });
   
   // Use async job pattern:
   app.post('/api/export', async (req, res) => {
     const jobId = crypto.randomUUID();
     queue.add('export', { jobId, ...req.body });
     res.status(202).json({
       jobId,
       status: 'processing',
       poll: `/api/export/${jobId}/status`
     });
   });
   
   app.get('/api/export/:id/status', async (req, res) => {
     const job = await queue.getJob(req.params.id);
     if (job.isCompleted)
       return res.json({ status: 'done', url: job.result });
     res.json({ status: 'processing', progress: job.progress });
   });

   Copy

How to verify the fix

• The previously-504ing endpoint now returns a response within the proxy timeout.
• Slow database queries have been indexed or paginated (check with EXPLAIN ANALYZE).
• Long-running operations use the async job pattern and return 202 immediately.
• Nginx error.log shows no new 'upstream timed out' entries.