How to Reduce Nginx 502 and 504 Gateway Errors

Practical steps to diagnose and fix nginx 502 and 504 errors — from upstream timeouts to worker limits — before they wake you up at 3am.

A wave of 502 and 504 errors is one of the most frustrating things to debug under pressure. Your nginx is running fine, your app server appears to be up, yet users are getting gateway errors. The problem almost never lives in nginx itself — it lives in the conversation between nginx and whatever is sitting behind it. Here's how to find the real cause and stop it from happening again.

Understand the Difference First

502 Bad Gateway means nginx got a response from the upstream — but the response was invalid, incomplete, or came from a crashed process. 504 Gateway Timeout means nginx gave up waiting because the upstream took too long to respond at all. They look the same to users but point to different root causes, so checking your nginx error log is step one.

Run this to see the last 50 upstream errors in real time: sudo tail -n 50 /var/log/nginx/error.log | grep upstream. Look for phrases like "connect() failed", "upstream timed out", or "no live upstreams". These strings tell you immediately whether you're dealing with a process crash (502 territory) or a slow backend (504 territory).

Fix the Most Common 502 Causes

A 502 usually means the upstream process — your Node app, Python/gunicorn, PHP-FPM, or whatever — is either dead, crashing on certain requests, or running out of worker slots. Start by confirming the upstream is actually listening:

• Check the upstream process is running: systemctl status gunicorn or pm2 list
• Confirm it's accepting connections on the expected socket or port: ss -tlnp | grep 8000
• Look at the upstream's own logs for uncaught exceptions or OOM kills: journalctl -u gunicorn --since '10 minutes ago'
• If using PHP-FPM, check the pool's pm.max_children setting — a common cause of 502 spikes under load
• Verify file descriptor limits aren't exhausted: cat /proc/$(pgrep gunicorn | head -1)/limits | grep 'open files'

For PHP-FPM specifically, edit /etc/php/8.x/fpm/pool.d/www.conf and increase pm.max_children to a value your RAM can support. A rough formula: divide available RAM (in MB) by the average PHP process size (check with ps --no-headers -o rss -C php-fpm8.2 | awk '{sum+=$1} END {print sum/NR/1024" MB"}'). Restart FPM after changes.

Fix the Most Common 504 Causes

A 504 means nginx is waiting and eventually giving up. The upstream is alive but responding too slowly — usually due to a slow database query, an external API call, or a CPU-bound task. The first thing to check is whether your nginx timeout values are set too aggressively short.

In your nginx upstream or server block, tune these three directives:

• proxy_connect_timeout 10s; — how long nginx waits to establish a connection to the upstream
• proxy_read_timeout 60s; — how long nginx waits for the upstream to send a response body (the most common culprit)
• proxy_send_timeout 60s; — how long nginx waits while transmitting a request to the upstream

Don't blindly raise these to 300s and call it done — that just hides slow queries behind a longer wait. Instead, profile what's actually slow. For slow database queries, enable slow query logging: in MySQL, set slow_query_log = 1 and long_query_time = 1 in /etc/mysql/mysql.conf.d/mysqld.cnf, then watch /var/log/mysql/mysql-slow.log. Fix the query, add an index, or move the work to a background job.

Add Upstream Health Checks and Retry Logic

If you run multiple upstream instances, nginx can automatically stop sending traffic to a failing one. In your upstream block, add failure detection:

upstream app_servers { server 127.0.0.1:8001 max_fails=3 fail_timeout=30s; server 127.0.0.1:8002 max_fails=3 fail_timeout=30s; }
This marks a server as unavailable after 3 failed attempts within 30 seconds, then retries it after 30 seconds. You can also add proxy_next_upstream error timeout http_502 http_504; in your location block so nginx automatically retries a failed request against the next upstream before returning an error to the user. Be careful with this on non-idempotent requests — you don't want POST requests retried blindly.

Keep Buffer and Queue Settings Realistic

Misconfigured buffers cause a surprising number of 502 errors. If your upstream sends a large response header and proxy_buffer_size is too small, nginx will return a 502. The default is usually 4k or 8k — if you use frameworks that set many cookies or JWT tokens in headers, bump it:

• proxy_buffer_size 16k; — for large response headers
• proxy_buffers 4 16k; — total buffer pool for response body
• proxy_busy_buffers_size 24k; — max data sent to client while response is still being read

After any nginx config change, always run nginx -t before reloading. A broken config will take down your whole server on reload. Once tests pass, use systemctl reload nginx rather than restart — reload is graceful and keeps existing connections alive.

Catching these errors before they spike is where tooling earns its keep. Opservo monitors your nginx error rate and upstream response times continuously, surfaces the likely cause in plain language, and can alert you the moment a pattern emerges — before it becomes a 3am incident. If you're managing production without a dedicated SRE, having that layer of interpretation between raw logs and a decision is genuinely useful.

The core takeaway: 502s and 504s are almost always symptoms of an unhealthy upstream or mismatched expectations between nginx and your app. Fix the underlying slowness or instability first, use nginx's retry and health-check features as a safety net, and tune your timeouts to reflect reality rather than hope.

Originally published on the Opservo blog — Opservo is the AI ops engineer for teams without an SRE. Free for 2 servers → https://getopservo.com/welcome