Common Nginx Errors and Fixes

Upstream vs edge

Nginx often sits in front of app servers or PHP-FPM. A 502 Bad Gateway usually means nginx could not get a valid HTTP response from upstream (connection refused, reset, or empty reply). A 504 Gateway Timeout means the upstream did not answer within proxy_read_timeout (or related timers). Read error_log at info or warn—the status line alone misleads clients.

Quick triage matrix

Symptom	Check first	Typical fix
502	`proxy_pass` host/port, unix socket path, upstream health	Start backend; align socket path; fix firewall between tiers
504	Slow DB or cold JVM; CDN to origin path	Optimize app; raise timeouts only with caps; add caching
413	`client_max_body_size` in server/location	Match API gateway and app limits on every tier
SSL handshake	Chain file, SNI `server_name` order	Use fullchain.pem; separate default_server block
`bind()` failed	`ss -tulpn` port collision	Stop duplicate master; fix systemd unit

Logging that pays off

Add structured access_log fields for request_time, upstream_status, and upstream_response_time so postmortems do not depend on reproducing in a browser.

Frequently Asked Questions

Q.Why does nginx report duplicate upstream name?

Two `upstream` blocks with the same name were merged from includes—search `conf.d` and snippets. Rename one block or deduplicate; reload order does not fix duplicate symbols.

Q.Why do I get 502 only on POST requests?

Often `client_body_temp_path` permissions, antivirus scanning upload temp files, or upstream rejecting large bodies. Compare GET vs POST in error_log and test with curl -d.

Q.Why is TLS wrong for some hostnames but not others?

SNI default server certificate mismatch—`openssl s_client -connect host:443 -servername host` per vhost. Ensure the first `server_name` on the listening socket matches expectations or set `default_server` intentionally.

Q.CDN shows 200 but origin through nginx returns 413—why?

The CDN accepted the upload; origin nginx still enforces `client_max_body_size`. Raise nginx and your app server consistently, not only the edge.

Q.How do I debug upstream connection refused?

Confirm whether `proxy_pass` uses TCP or a unix socket, then `curl --unix-socket` or `nc -vz` to the same target from the nginx host. Container networks often use different service DNS names than the host.

Q.What does worker_connections exhausted mean?

Each connection consumes a slot—raise `worker_connections` together with OS `ulimit` / `worker_rlimit_nofile`. Also check slowloris or stuck long-poll clients holding sockets open.

Q.Why does the browser show a generic error while nginx knows more?

Many teams hide upstream bodies for security. Read `error_log` and extend access_log—do not rely on the HTML error page text alone.

Q.How should I capture one failing request for support?

Correlate `X-Request-ID` from access_log with error_log timestamps, include `upstream_addr` and `upstream_status`, and redact cookies before sharing captures.