Skip to content
DevOps AI ToolKit
Newsletter
NGINX Troubleshooting Toolkit

NGINX Troubleshooting Toolkit

Use this NGINX troubleshooting toolkit to diagnose 502 Bad Gateway, 504 Gateway Timeout, upstream connection failures, TLS/SSL errors, config emerg errors, and rate limiting.

Paste your error and get a triage plan.

Paste a log line, CLI error, stack trace, service failure, or config snippet and get a structured troubleshooting plan. Your snippet is carried straight into the AI Incident Response Assistant with NGINX context prefilled.

Open the NGINX Incident Assistant → Browse NGINX prompts

Do not paste secrets, tokens, private keys, passwords, or customer data. Your snippet stays in your browser until you open the assistant.

Top 25 NGINX Errors and Failure Modes

The production failures engineers hit most — each links to a full cause → fix → prevention guide.

502 Bad Gateway

NGINX received an invalid or empty response from an upstream backend it was proxying to.

504 Gateway Timeout

The upstream server did not respond within proxy_read_timeout, so NGINX gave up waiting.

upstream timed out (110: Connection timed out)

A slow or overloaded backend exceeded proxy_connect_timeout or proxy_read_timeout while NGINX waited.

connect() failed (111: Connection refused) to upstream

The backend port is closed or the service is down, so NGINX cannot establish a TCP connection.

no live upstreams while connecting to upstream

Every server in the upstream block is marked failed, leaving NGINX with nowhere to route requests.

recv() failed (104: Connection reset by peer)

The upstream abruptly closed the connection mid-response, often from a backend crash or keepalive mismatch.

upstream sent too big header

Backend response headers exceeded proxy_buffer_size, causing NGINX to reject them with a 502.

upstream sent no valid HTTP/1.0 header

The backend returned malformed or non-HTTP output that NGINX could not parse as a valid response.

413 Request Entity Too Large

The request body exceeded client_max_body_size, so NGINX blocked the upload before reaching the backend.

503 Service Unavailable (rate limiting)

A limit_req or limit_conn zone rejected requests that exceeded the configured rate or connection cap.

worker_connections are not enough

Concurrent connections outgrew the worker_connections limit, causing NGINX to drop or queue traffic.

too many open files (24: EMFILE)

NGINX hit the file-descriptor ulimit, blocking new sockets and file handles under load.

SSL_do_handshake() failed

The TLS handshake broke down over protocol, cipher, or SNI mismatches between client and NGINX.

SSL certificate problem / verify failed

A missing chain, expired cert, or hostname mismatch caused clients or upstreams to reject the certificate.

bind() to 0.0.0.0:80 failed (address already in use)

Another process already holds the listen port, preventing NGINX from starting or reloading.

[emerg] directive not allowed here / duplicate location

A directive placed in the wrong context or a repeated location block fails config validation.

could not build server_names_hash

Long or numerous server_name values overflowed the hash bucket, requiring server_names_hash tuning.

rewrite or internal redirection cycle

A loop in rewrite rules or try_files sends requests around indefinitely until NGINX aborts with a 500.

permission denied while connecting to upstream (SELinux)

SELinux booleans block NGINX from opening network connections to the backend, returning a 502.

client intended to send too large body guide coming soon

An upload larger than client_max_body_size triggered NGINX to reject the request during the request phase.

403 Forbidden guide coming soon

NGINX denied access due to file permissions, an index/autoindex issue, or an explicit deny rule.

404 Not Found (try_files / root) guide coming soon

A misconfigured root, alias, or try_files directive points NGINX at a path that does not exist.

499 Client Closed Request guide coming soon

The client disconnected before NGINX finished the response, usually from a slow upstream or short client timeout.

[emerg] unknown directive guide coming soon

A typo or a directive from an unloaded module makes nginx -t reject the configuration.

host not found in upstream guide coming soon

NGINX cannot resolve an upstream hostname at startup because DNS or a resolver directive is missing.

Validate your config before you redeploy

Catch the structural mistakes that cause outages — 100% in your browser, nothing uploaded.

NGINX Config ValidatorYAML Validator Not sure? Start with the Incident Assistant →

Best NGINX Prompts

Turn symptoms, logs, and config into a structured plan with prompts tuned for NGINX.

Debug NGINX 502 / 504 Upstream Errors

Root-cause bad gateway and gateway timeout failures

Use this prompt

Harden NGINX TLS / SSL Configuration

Fix handshake and certificate problems, tighten ciphers

Use this prompt

Fix NGINX Location Block Precedence

Resolve unexpected routing and 404s from location matching

Use this prompt

Design NGINX Rate Limiting (limit_req / limit_conn)

Throttle abuse without triggering false 503s

Use this prompt

Secure NGINX Reverse Proxy Vhost

Build a safe proxy_pass server block for microservices

Use this prompt

Troubleshoot NGINX Config That Fails nginx -t

Decode emerg errors and directive-context mistakes

Use this prompt

Fix NGINX Large Uploads & Request Buffering

Tune client_max_body_size and buffering for 413s

Use this prompt

Tune NGINX Workers & Keepalive Performance

Right-size worker_connections and keepalive under load

Use this prompt

Download the NGINX Troubleshooting Runbook Pack

Checklists for a proxy that is 502/504-ing, mis-routing, or failing TLS.

  • 502 / 504 upstream triage
  • proxy_pass & DNS resolution
  • TLS / SSL certificate checks
  • location & rewrite precedence
  • worker_connections & open files
Download the NGINX Runbook Pack

All NGINX Troubleshooting Guides

Grouped by failure-mode type — each guide covers cause, fix, validation, and prevention.

Authentication & TLS (14)

Nginx Error: 'cannot load certificate ... BIO_new_file() failed (fopen: No such file or directory) Nginx Error: 'could not open error log file: open() '/var/log/nginx/error.log' failed (13: Permission denied) Nginx Error: 'directory index of '/var/www/html/app/' is forbidden Nginx Error: 'mkdir() '/var/cache/nginx/proxy_temp' failed (13: Permission denied) Nginx Error: 'open() '/var/www/html/index.html' failed (13: Permission denied) Nginx Error: 'peer closed connection in SSL handshake while SSL handshaking Nginx Error: 'upstream SSL certificate verify error: (20:unable to get local issuer certificate) SSL_CTX_use_PrivateKey_file failed key values mismatch (13: Permission denied) while connecting to upstream SSL_do_handshake() failed AI-Assisted NGINX auth_request for SSO and Forward Auth 403 Forbidden SSL_do_handshake() failed Hardening NGINX TLS/SSL With AI Without Shipping Hallucinated Ciphers

Networking (23)

Nginx Error: 'socket() [::]:80 failed (97: Address family not supported by protocol) Nginx Error: 'no port in upstream Nginx Error: 'upstream sent invalid chunked response while reading upstream' — Cause and Fix (99: Cannot assign requested address) no resolver defined to resolve upstream timed out (110: Connection timed out) host not found in upstream upstream prematurely closed connection no live upstreams while connecting to upstream recv() failed (104: Connection reset by peer) upstream sent no valid HTTP/1.0 header worker_connections are not enough AI-Assisted Blue-Green Deployments with NGINX Upstreams Diagnosing Slow NGINX Requests With AI and Upstream Timing 502 Bad Gateway 504 Gateway Time-out [emerg] bind() to 0.0.0.0:80 failed (98: Address already in use) connect() failed (111: Connection refused) while connecting to upstream upstream sent too big header AI-Assisted NGINX Proxy Caching and Microcaching AI-Assisted NGINX Reverse Proxy for Microservices Configuring the NGINX Ingress Controller in Kubernetes With AI Debugging NGINX 502 Bad Gateway and 504 Gateway Timeout With AI

Deployment & Builds (1)

could not build server_names_hash

Runtime (1)

worker process exited on signal 11

Performance (2)

Nginx Error: 'shared memory zone 'one' conflicts with already declared size (24: Too many open files)

API errors (4)

Nginx Error: '499 Client Closed Request 400 Request Header Or Cookie Too Large AI-Assisted NGINX Large File Uploads and Request Buffering 413 Request Entity Too Large

Configuration (3)

invalid number of arguments in directive unknown directive AI-Assisted NGINX CORS Configuration Without the Wildcard Trap

Other (20)

Nginx Error: 'client intended to send too large body Nginx Error: 'a duplicate default server for 0.0.0.0:80 Nginx Error: 'getpwnam('nginx') failed Nginx Error: 'PEM routines:get_name:no start line ... Expecting: ANY PRIVATE KEY Nginx Error: 'root directive is duplicate 503 Service Temporarily Unavailable NGINX Warning Guide: 'conflicting server name ignored' — Fix Duplicate Vhosts unexpected end of file, expecting } duplicate location open() failed (2: No such file or directory) rewrite or internal redirection cycle AI-Assisted NGINX Compression with gzip and Brotli AI-Assisted NGINX HTTP/3 and QUIC Setup AI-Assisted NGINX Access and Error Log Analysis AI-Assisted NGINX Scripting with OpenResty and Lua [emerg] directive is not allowed here AI-Assisted NGINX Performance Tuning Without Cargo-Culting AI-Assisted NGINX Rate Limiting and Abuse Control Migrating Apache .htaccess to NGINX with AI Understanding NGINX Location Block Precedence With AI
Browse the full NGINX category

NGINX troubleshooting FAQ

Why does NGINX return 502 Bad Gateway?
A 502 means NGINX reached the upstream but got an invalid or empty reply. Common causes are a crashed or overloaded backend, a wrong proxy_pass address or port, a connection reset, or response headers larger than proxy_buffer_size. Check the upstream service health and the NGINX error log for the exact reason before tuning buffers or timeouts.
How do I fix NGINX 504 Gateway Timeout?
A 504 means the upstream did not respond within the configured timeout. First confirm the backend is actually slow rather than down, then raise proxy_connect_timeout, proxy_send_timeout, and proxy_read_timeout to match realistic response times. For genuinely long requests, fix the slow query or endpoint instead of masking it with ever-larger timeouts.
What causes 'connect() failed (111: Connection refused)' to upstream?
This error means nothing is listening on the upstream host and port, so the TCP connection is refused. Verify the backend process is running, is bound to the address NGINX proxies to (not just localhost when they differ), and that no firewall or SELinux rule blocks the port. It is almost always a backend or networking problem, not an NGINX one.
How do I fix an NGINX SSL handshake failure?
SSL_do_handshake() failures usually come from protocol or cipher mismatches, a missing SNI match, or a client presenting an unsupported TLS version. Ensure ssl_protocols and ssl_ciphers allow modern TLS 1.2/1.3, that the correct certificate and full chain are served for each server_name, and that any upstream TLS uses proxy_ssl settings that match the backend.
Why does NGINX return 413 Request Entity Too Large?
NGINX rejects a request whose body exceeds client_max_body_size, which defaults to 1 MB. Raise it in the relevant http, server, or location block to the largest upload you expect, and if you proxy to a backend make sure the backend's own body limit is at least as high. Reload NGINX after the change for it to take effect.
When should I use the NGINX Config Validator?
Use the NGINX Config Validator before every reload or deploy to catch emerg errors like duplicate locations, unknown directives, directives in the wrong context, and server_names_hash overflows without touching production. It is especially useful in CI or when refactoring large vhost files, so you fail fast on syntax and structure instead of during a live nginx -s reload.