Fix NGINX 502 Bad Gateway

A 502 from NGINX means the proxy could not get a valid response from its upstream. Start inside the same network environment as NGINX.

Check the Application and Address

  1. Confirm the application process is running.
  2. Check which address and port the application is listening on.
  3. Request the upstream URL from the host or container that runs NGINX.

If NGINX and the app are separate containers, check that they share a network and that the upstream uses the app’s service name and container port. See the NGINX Docker setup example.

Check Protocol and Logs

Check whether the upstream expects HTTP or HTTPS and compare that with proxy_pass. Read the error log at the time of the failure. A refused connection points to a different issue from a TLS handshake error or an upstream closing the connection early.

Match the Message to the Next Step

Illustrative log messageNext check
connect() failed (111: Connection refused)Confirm that the app is listening on the upstream host and port from the NGINX network.
upstream timed outCheck app response time and dependencies. This can also surface as a 504.
SSL_do_handshake() failedConfirm the upstream protocol, server name and certificate chain. Retain verification for a remote TLS upstream.

Reproduce a Connection Refusal

After the local reverse proxy lab returns proxy-lab-ok, stop only the lab’s Python upstream. The NGINX process stays running.

kill "$app_pid"
wait "$app_pid" 2>/dev/null || true
curl --noproxy '*' -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8088/
tail -n 5 "$lab/error.log"

Expect 502 while the port has no listener. On Linux, the error log normally names the upstream address and says Connection refused. Start the same upstream again, verify it directly, and then verify through NGINX.

python3 -m http.server 3000 --bind 127.0.0.1 --directory "$lab/www" &
app_pid=$!
curl --noproxy '*' --retry 3 --retry-connrefused -fsS http://127.0.0.1:3000/
curl --noproxy '*' -fsS http://127.0.0.1:8088/
nginx -p "$lab/" -c nginx.conf -s stop
kill "$app_pid"

Run the direct check once the upstream has started listening. Expect both requests to print proxy-lab-ok before cleanup. In this example the configuration stays the same. Restoring the missing listener repairs the route.

Verify the Fix

After editing, run nginx -t and reload only if the configuration is valid. Check both the direct upstream and the URL through NGINX.

  1. Connection refused. Confirm the app is listening at the configured port from the NGINX host or container. A direct HTTP request should return a status line.
  2. Upstream timed out. Time a direct request to the same path from the same network. Investigate the slow handler or unavailable dependency before increasing timeouts.
  3. TLS handshake failure. Verify the upstream expects HTTPS, the hostname matches its certificate, and the trust chain is valid. Keep verification enabled.

After the direct check passes, repeat the proxied request and check that the matching log error does not recur.