| Users see 502 or 504 errors from a proxied service, often after a deploy | The error log line, which separates an upstream that closed the connection, one that timed out and one that refused it. Then the upstream address, the read and connect timeouts, and whether the upstream closes idle keepalive connections sooner than NGINX reuses them. | Timeout and keepalive alignment, or the upstream service itself |
|---|
| The error log reports that worker connections are not enough | worker_connections against real concurrency, the file descriptor limit the workers actually have, and which upstream is holding connections open. Each proxied request counts a client connection and an upstream connection. | Connection and descriptor limits, per-upstream caps, then timeouts |
|---|
| A reload succeeds, but old workers stay in the process list for hours | Long-lived connections such as WebSockets or streaming responses, which keep an old worker until they close, and whether worker_shutdown_timeout is set. | A deliberate shutdown timeout and client reconnect behavior |
|---|
| Behavior changed after upgrading from 1.28 or older | A diff of the effective configuration against the defaults that changed in the 1.29 line: upstream keepalive on by default, proxy_http_version 1.1 and no Connection header from 1.29.7, Host and port validation following RFC 3986 from 1.29.4, and a lone LF in a chunked body treated as an error. | Explicit settings in the configuration, and fixes for clients that relied on the old behavior |
|---|
| Browsers or API clients fail the TLS handshake after a certificate change | Certificate chain order, the default server for requests without SNI, protocol and cipher settings, and whether the reload actually ran on every node. | Full chain installed, default server set, reload verified per node |
|---|
| Errors continue after a backend changed address, until the next reload | How the upstream is defined. Without the resolve parameter or a resolver, NGINX resolves a hostname when it loads the configuration. The resolve parameter is in open source since 1.27.3 and needs a resolver directive. | Resolver and the resolve parameter, or a design that does not depend on DNS changes |
|---|
| Cached pages expire together and the origin is hit by a burst of identical requests | The proxy cache settings: whether cache locking is on, whether stale responses may be served while an entry refreshes, and the validity time of the busiest entries. | proxy_cache_lock and stale-while-updating settings |
|---|
| An Ingress change is not applied by the community Ingress NGINX controller | The controller log for a failed configuration test. A bad annotation or snippet can stop the controller from reloading for every Ingress. The controller is also archived, so there will be no fix release. | Correct the snippet, then plan the exit with the hub's migration work |
|---|