Nginx '502 Bad Gateway' when proxying to an app (upstream down, wrong port, unix socket permissions): how do I find the cause and fix it?

Cause: nginx returns 502 when it cannot get a valid response from the server named in proxy_pass or an upstream block. Typical reasons: the app is not running or crashed, it listens on a different port or address than nginx is told to use, a unix socket path is wrong or not accessible to the nginx worker user, or the app closed the connection or sent something invalid. The nginx error log says which one. Fix (best first): 1. Read the error log (commonly /var/log/nginx/error.log; check error_log in your config). Messages about connection refused mean nothing is listening at that address; permission denied on a socket means a user/group problem; a timeout means the app is hung or slow. 2. Confirm the app is up and bound where nginx expects, from the same host or container network as nginx (for example with ss -ltnp or curl against the exact proxy_pass target). Inside containers, 127.0.0.1 is the nginx container itself, so use the service name. 3. Make proxy_pass match exactly: scheme, host, port. For a unix socket the syntax is proxy_pass http://unix:/path/to/app.sock:/; (socket path between colons). 4. For sockets, make sure the nginx worker user can traverse every directory in the path and read/write the socket (group membership or a shared group on the socket), rather than loosening permissions to everyone. 5. In an upstream group, a server that fails is marked unavailable for fail_timeout (default 10s after max_fails, default 1). A brief app restart can therefore keep returning 502 for a few seconds; add health checks or retries, or fix the app start-up time. 6. If the app is slow rather than down, look at proxy_connect_timeout (default 60s) and the read timeouts and fix the slow code path instead of only raising limits. Verify: nginx -t passes, the reload succeeds, the request through nginx returns the app response, and no new upstream errors appear in the error log. Sources: https://nginx.org/en/docs/http/ngx_http_proxy_module.html https://nginx.org/en/docs/http/ngx_http_upstream_module.html