How to Fix an Nginx 502 Bad Gateway

What a 502 Bad Gateway actually means

Nginx returns 502 when it is acting as a reverse proxy and the upstream server (your app) either refused the connection, wasn't listening where nginx expected, or returned a malformed response. The nginx process itself is healthy - the problem is between nginx and your backend.

Step 1: confirm it and read the error log

curl -i http://localhost/        # confirms the 502
tail -n 20 /var/log/nginx/error.log

The error log names the cause directly. The most common line is:

connect() failed (111: Connection refused) while connecting to upstream,
upstream: "http://127.0.0.1:8080/"

Connection refused to a specific upstream: is the smoking gun - nginx is dialing a port nothing is listening on.

Step 2: check where the app is really listening

ss -ltnp | grep LISTEN     # what ports are actually open

Compare that to the proxy_pass / upstream in your nginx config:

upstream backend {
    server 127.0.0.1:8080;   # <- nginx dials 8080
}

If the app is on 3000 but nginx points at 8080, that mismatch is your 502.

Step 3: fix the upstream and reload

Point nginx at the real port and reload (no full restart needed):

# in /etc/nginx/nginx.conf, set the upstream to the real port, then:
nginx -t            # validate the config first
nginx -s reload     # graceful reload

curl http://localhost/ should now return 200.

The other common 502 causes

• Backend is down or crashed - start it; curl it directly (curl 127.0.0.1:3000) to confirm it answers.
• Wrong protocol/socket - app listens on a Unix socket but nginx uses a TCP port (or vice versa).
• Backend timeout - a slow upstream trips proxy_read_timeout; raise it or fix the slow response.
• SELinux/firewall - blocks nginx from connecting to the upstream port.