Nginx 502 Bad Gateway: upstream errors decoded

A 502 from Nginx means the proxy reached out to your app and got nothing usable back. The Nginx error log names the cause in one line — here is what each line means.

What the error means

Nginx is fine. The upstream — PHP-FPM, Node, Gunicorn, a container — refused the connection, closed it early, or sent an invalid response.

Read the error log

sudo tail -n 50 /var/log/nginx/error.log

Match the message

connect() failed (111: Connection refused) The app isn't listening on that address. Check it's running and the port matches proxy_pass.

sudo ss -ltnp | grep 3000

connect() to unix:/run/php/php8.3-fpm.sock failed (13: Permission denied) Nginx's user can't read the socket. Align listen.owner / listen.group in the FPM pool with the Nginx user.

upstream prematurely closed connection The app crashed or timed out mid-request. Check the app's own logs.

upstream sent too big header Large cookies or auth headers. Raise the buffers:

proxy_buffer_size 16k;
proxy_buffers 8 16k;
proxy_busy_buffers_size 32k;

(13: Permission denied) while connecting to upstream on RHEL/CentOS SELinux is blocking the proxy:

sudo setsebool -P httpd_can_network_connect 1

Verify

sudo nginx -t && sudo systemctl reload nginx
curl -I https://your-site.example

Expect HTTP/2 200.