How to Diagnose and Fix the 9 Most Common Nginx Errors

1️⃣ 502 Bad Gateway

The server receives the client request but cannot obtain a proper response from the upstream service.

Backend service not started or crashed

Check: systemctl status, ps aux | grep <service>, netstat -tulnp | grep <port> Fix: Start or restart the backend service.

Firewall / security group blocking

Check: telnet <backend_ip> <port> or curl -v http://backend:port Fix: Open the required port.

Nginx configuration error

Check proxy_pass or upstream address and port.

Fix: Correct the configuration and reload with nginx -s reload.

Backend timeout

Fix: Increase timeout values, e.g.

proxy_connect_timeout 60s;

proxy_send_timeout 60s;

proxy_read_timeout 60s;

Insufficient application processes (e.g., PHP‑FPM)

Check PHP‑FPM status and connection count.

Fix: Adjust pm.max_children and optimise code.

2️⃣ 504 Gateway Time‑out

The upstream server did not respond within the configured time.

Slow backend processing Optimise database queries, API calls or application logic; increase proxy_read_timeout if necessary.

Network latency or packet loss Use ping , traceroute or mtr to diagnose and coordinate with network/cloud operators.

3️⃣ Client real IP loss

Backend sees only the Nginx IP.

Solution:

proxy_set_header Host $host;</code>
<code>proxy_set_header X-Real-IP $remote_addr;</code>
<code>proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;</code>
<code>proxy_set_header X-Forwarded-Proto $scheme;

⚠️ Ensure the backend parses X-Forwarded-For.

4️⃣ WebSocket proxy failure

Nginx does not handle protocol upgrade by default; manual configuration is required.

location /ws/ {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

5️⃣ Load balancing not effective

Place upstream block inside the http context.

Default round‑robin can be changed to ip_hash (session persistence) or least_conn.

Configure health checks with max_fails and fail_timeout.

For domain resolution, use resolver (e.g., resolver 8.8.8.8 valid=30s;).

6️⃣ Static file access issues or slowness

Path errors – verify alias or root.

Permission problems – ensure the Nginx user has read rights.

Optimization example

location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
    root /path/to/static/files;
    expires 30d;
    access_log off;
}

7️⃣ Large file upload failure (413 Request Entity Too Large)

The default request body size is too small. client_max_body_size 100m; ⚠️ Also verify upload limits on the backend application.

8️⃣ SSL/TLS errors

Incomplete certificate chain – use fullchain.pem.

Improper protocol configuration – enable modern protocols.

ssl_protocols TLSv1.2 TLSv1.3;</code>
<code>ssl_ciphers HIGH:!aNULL:!MD5;

9️⃣ Cache miss or poor performance

Backend response caching

proxy_cache my_cache;</code>
<code>proxy_cache_valid 200 1m;

Static resource caching

expires 30d;</code>
<code>add_header Cache-Control "public";

Rate limiting and anti‑scraping

Prevent malicious high‑concurrency traffic.

limit_conn_zone $binary_remote_addr zone=addr:10m;</code>
<code>limit_req_zone $binary_remote_addr zone=one:10m rate=10r/s;</code>
<code>location / {
    limit_conn addr 10;
    limit_req zone=one burst=20 nodelay;
}

General troubleshooting steps

Logs

Error log: tail -f /var/log/nginx/error.log Access log: review request flow.

Configuration check

Validate syntax: nginx -t Reload gracefully: nginx -s reload Common commands

Show listening ports: ss -lntp Find port usage: lsof -i :80 Show compiled modules: nginx -V Local request test:

curl -v http://localhost:<port>

Conclusion

Nginx issues can be grouped into error‑code problems (502, 504), functional problems (IP handling, WebSocket, load balancing, uploads, SSL), and performance problems (static files, cache, rate limiting). Using logs, configuration validation, and network checks in three steps typically locates and resolves the majority of problems quickly.