Welcome to LeviFREE's Blog

1. Distinguish Between 502 and 504 First#

• 502: Nginx can contact the upstream, but the upstream returns an anomaly or the connection fails.
• 504: Nginx waits for the upstream and times out.

This distinction will determine the direction of your troubleshooting.

2. The First Scene: Check the Logs#

1
sudo tail -n 200 /var/log/nginx/error.log
2
sudo tail -n 200 /var/log/nginx/access.log

Focus on:

• connect() failed
• upstream timed out
• no live upstreams

3. Verify if the Upstream Service is Alive#

1
curl -I http://127.0.0.1:8080
2
ss -tulpen | rg 8080

If you can’t even access the upstream locally, fix the upstream application first; don’t modify Nginx right away.

4. Check the Proxy Configuration#

Common issues:

• proxy_pass address is wrong.
• Upstream port changed but wasn’t synced.
• Missing Host header causing upstream routing to fail.

Reference:

1
location / {
2
  proxy_pass http://127.0.0.1:8080;
3
  proxy_set_header Host $host;
4
  proxy_set_header X-Real-IP $remote_addr;
5
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
6
  proxy_connect_timeout 5s;
7
  proxy_read_timeout 60s;
8
}

5. Troubleshooting Resource Bottlenecks#

If the failure is sporadic, focus on resources:

1
top
2
free -m
3
df -h

High-frequency root causes:

• Insufficient memory causing the upstream process to be killed by OOM.
• CPU maxed out causing response timeouts.
• Disk full causing log or temporary file writes to fail.

6. Docker Scenario Supplement#

If Nginx and the upstream are in Docker:

• Check if the containers are in the same network.
• proxy_pass should point to the service name, not localhost.
• Is the container restart policy reasonable?

7. Verification After Fixing#

1. nginx -t to check if the configuration is valid.
2. Smooth reload: systemctl reload nginx.
3. Continuously stress test / access for 5-10 minutes to observe if it recurs.

Summary#

The key to 502/504 is not “restarting fixed it”, but establishing a stable troubleshooting sequence: Logs -> Upstream -> Configuration -> Resources. Once the process is fixed, the failure recovery time will be significantly shortened.