Nginx 502 Bad Gateway

Separate Nginx config, upstream listener, proxy target, and application failure before reloading services.

Safest first command

sudo nginx -t

Before you run this

Expected output: Nginx reports whether configuration syntax is OK or identifies the file and line with a problem.

When not to use it: Do not reload Nginx before testing config and confirming the upstream target. A reload can turn one bad vhost into a wider outage.

Expected output example

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

How to read the result

A successful config test means syntax is not the immediate blocker. Next, inspect proxy targets, listener state, and recent upstream logs.

Test Nginx and find the upstream

A 502 usually means Nginx could not talk to the upstream. Prove config validity, then map proxy targets and listener state.

sudo nginx -t
grep -RInE 'proxy_pass|fastcgi_pass|uwsgi_pass' /etc/nginx 2>/dev/null
ss -ltnp

Use logs to confirm the failing path

Group 5xx responses by URL path and inspect recent service logs for the upstream process.

Common causes

Upstream service is not listening
Wrong proxy_pass host or port
Unix socket path or permission problem
Application crash or timeout
Nginx config syntax error before reload

What not to change yet

Do not reload before nginx -t succeeds.
Do not kill the upstream process until you know whether a supervisor owns it.
Do not rewrite proxy config before checking the current target.

platform notes

Distro and service notes

systemd

Use journalctl for both nginx and the upstream service when systemd manages them.

Docker

Check published ports and container health before editing Nginx.

Permissions

Unix socket upstreams can fail because Nginx cannot access the socket directory.

supporting commands