HTTP 504 Gateway Timeout
ID: networking/http-504-gateway-timeout
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| any | active | — | — | — |
Root Cause
A reverse proxy or gateway did not receive a timely response from the upstream server. The backend is reachable but too slow to respond within the proxy's configured timeout. This often indicates backend performance issues, database lock contention, or long-running operations.
genericWorkarounds
-
85% success Optimize the backend service to respond within the timeout
1. Identify slow endpoints from proxy logs (which URLs cause 504s) 2. Profile the backend: check database query performance, external API calls, CPU usage 3. Add database indexes for slow queries: EXPLAIN ANALYZE on suspect queries 4. Implement caching for expensive operations (Redis, Memcached) 5. Offload long-running operations to background workers (Celery, Sidekiq) 6. Set appropriate timeouts on backend external dependencies to fail fast 7. Monitor response times: add APM tooling (Datadog, New Relic, Prometheus)
-
82% success Tune proxy timeout settings appropriately and implement async patterns
1. Check current proxy timeout: nginx proxy_read_timeout, proxy_connect_timeout, proxy_send_timeout 2. Set reasonable timeouts based on actual backend SLAs (e.g., proxy_read_timeout 30s) 3. For long operations, implement async request/response pattern: return 202 Accepted with a status polling URL 4. Configure proxy buffering: proxy_buffering on; proxy_buffer_size 16k; 5. Enable keepalive to backend: upstream backend { keepalive 32; } 6. Set up timeout-specific error pages to provide user-friendly feedback
Dead Ends
Common approaches that don't work:
-
Only increase the proxy timeout without investigating backend performance
75% fail
Increasing the timeout is a band-aid that allows requests to queue longer, consuming proxy worker threads and memory. If the backend is genuinely slow due to a bug or resource exhaustion, longer timeouts just delay the inevitable failure and reduce overall throughput for all users.
-
Add more proxy instances without fixing the slow backend
80% fail
More proxies just mean more connections waiting on the same slow backend. The backend becomes even more overloaded with additional concurrent requests, potentially making the timeout problem worse rather than better.