A 504 Gateway Timeout means Nginx is acting as a reverse proxy and the upstream server (your app) didn’t respond within the timeout period.

What causes this error

1. Upstream server is slow — your app takes too long to process the request
2. Upstream server is down — the app crashed or isn’t running
3. Timeout too short — Nginx’s default proxy timeout is 60 seconds
4. Network issue — Nginx can’t reach the upstream server

Fix 1: Increase Nginx timeouts

location / {
    proxy_pass http://localhost:3000;
    proxy_connect_timeout 300s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;
    send_timeout 300s;
}

Reload Nginx: sudo nginx -s reload. See our Nginx cheat sheet for more configuration options.

Fix 2: Check if the upstream is running

# Is your app actually running?
curl -I http://localhost:3000/health

# Check the process
ps aux | grep node  # or python, java, etc.

# Check the port
ss -tlnp | grep 3000

Fix 3: Fix the slow endpoint

If the upstream is running but slow:

# Check Nginx error logs for which upstream is timing out
tail -f /var/log/nginx/error.log
# Look for: "upstream timed out (110: Connection timed out)"

Common causes of slow responses:

• Unoptimized database queries (add indexes — see our PostgreSQL cheat sheet)
• External API calls without timeouts
• Large file processing (move to background jobs)

If your upstream is a Docker container, make sure the container has enough resources and the network is configured correctly.

Fix 4: Add buffering

location / {
    proxy_pass http://localhost:3000;
    proxy_buffering on;
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
}

Quick diagnostic

# Test upstream directly (bypass Nginx)
time curl http://localhost:3000/slow-endpoint

# If this is also slow, the problem is your app, not Nginx
# If this is fast, the problem is Nginx configuration