An Nginx reverse proxy is usually the first thing between your users and your application. When it breaks, the symptoms are clear but the cause is often one of a handful of repeatable mistakes.

Symptom 1: 502 Bad Gateway

A 502 means Nginx could not get a valid response from the upstream. Work through this list in order:

  1. Is the upstream actually listening? ss -ltnp | grep 8080
  2. Is it bound to an address Nginx can reach? Localhost-only bindings break remote proxies.
  3. Is SELinux or a firewall blocking the connection? Check the audit log.
curl -I http://127.0.0.1:8080
tail -f /var/log/nginx/error.log

Symptom 2: 504 Gateway Timeout

The upstream is slow. Raise the proxy timeouts only after confirming the upstream is healthy under load, otherwise you are hiding a problem.

proxy_connect_timeout 5s;
proxy_send_timeout    30s;
proxy_read_timeout    30s;

Symptom 3: missing request headers

Backend applications often need the real client address. Without the forwarded headers every log entry shows the proxy IP.

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

If your app forces HTTPS redirects, always pass X-Forwarded-Proto and make the app trust the proxy, otherwise you can end up in a redirect loop.

Symptom 4: websocket disconnects

Websockets need an upgrade header and long timeouts. Missing upgrades cause connections to drop after roughly 60 seconds.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ""      close;
}
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;

For more background on request routing, see the official proxy module documentation.