Nginx 502 Bad Gateway? Locate It in 5 Steps

Understand what 502 means

502 Bad Gateway means Nginx received a response from upstream but it was invalid (connection refused, connection reset, protocol error). So the focus is the link between Nginx and the service behind it — not Nginx’s static serving.

Step 1: is the backend process alive

The most common cause is the backend being down or not listening on the expected port. Check the process and port first.

ps aux | grep <your-app>
ss -ltnp | grep <port>     # 确认后端确实在监听 Nginx 配置的端口

Step 2: is the upstream address/port correct

Verify the host:port in `proxy_pass` is actually reachable. In container environments it is especially easy to mistype the service name or port.

location /api/ {
  proxy_pass http://127.0.0.1:8080;   # 确认 8080 确为后端端口
}

Step 3: is it a timeout

When the backend is slow (big query, cold start), Nginx gives up and returns 502. Raise the proxy timeouts appropriately.

proxy_connect_timeout 60s;
proxy_read_timeout 60s;
proxy_send_timeout 60s;

Step 4: resources and connection limits

An exhausted backend connection pool, file-descriptor (fd) limit, or Nginx worker connections cap can also surface as 502. Check the system/service resource levels.

Step 5: close the loop with error.log

Nginx’s `error.log` states the exact cause, e.g. `connect() failed (111: Connection refused)` or `upstream prematurely closed`. Match the keyword to the step above and you will usually hit the root cause in one shot.

tail -f /var/log/nginx/error.log