Learning nginx - Troubleshooting & Debugging NGINX

#Introduction

At some point, production will act up: the website suddenly returns 502, an upload fails with 413, or a page refuses access with 403. This Episode 19 equips you with diagnostic tools and a mental model for troubleshooting NGINX quickly and systematically.

You'll use nginx -t and nginx -T to validate and dissect configuration, read error logs including debug level, and understand the causes and solutions of the most popular error codes. This is the episode that will save you at 3 AM when production goes down.

#Main Diagnostic Commands

#nginx -t: Test Syntax

The first command for any configuration suspicion:

sudo nginx -t

nginx -t checks all configuration files and shows the full error location with the file name and line number if something is wrong.

#nginx -T: Dump the Combined Configuration

Sometimes the configuration is split across many files and errors aren't visible. nginx -T merges everything:

sudo nginx -T | grep -n "server_name" | head -20

nginx -T displays the entire configuration after all include processing — including configuration from other modules you may not remember writing.

#Reading and Analyzing the Error Log

#Log Levels and Location

The error log holds all serious problems:

sudo tail -50 /var/log/nginx/error.log

Log levels range from debug (most detailed) to emerg. The distro default is usually warn or error. During deep troubleshooting, temporarily raise the level:

error_log /var/log/nginx/error.log debug;

With debug, NGINX writes very complete detail: the location selection process, upstream negotiation, and connection events. Enable it only while debugging, then return to normal level because debug is very disk-hungry.

#Troubleshooting Popular HTTP Error Codes

#502 Bad Gateway

NGINX can't reach the backend. Common causes:

• Backend down or wrong port in proxy_pass.
• Backend only listening on localhost but NGINX points to another IP.
• Protocol mismatch: proxy_pass to HTTPS but the backend is HTTP.

Check with curl and look at the error log:

curl -I http://localhost:3000
tail -20 /var/log/nginx/error.log

curl -I http://localhost:3000 tests the backend directly. If curl fails, the problem is in the backend, not NGINX.

#504 Gateway Timeout

The backend received the request but took too long to respond. Raise the timeout or fix the backend:

location / {
    proxy_pass http://backend_app;
    proxy_read_timeout 90s;
    proxy_connect_timeout 10s;
}

Also check slow database queries and endpoints doing heavy work without a time limit.

#403 Forbidden

NGINX found the file but isn't allowed to read it. Common causes:

• Wrong folder or file permissions: NGINX runs as the www-data user and must be able to enter the whole path to the file.
• index not found in a directory without autoindex.
• Caught by a deny all; access control rule.

sudo -u www-data ls -la /var/www/example/

If the www-data user can't read the folder, set the owner and permissions with chown and chmod.

#413 Request Entity Too Large

The upload was rejected because it exceeds client_max_body_size:

server {
    client_max_body_size 50M;
}

Adjust it to match the application's upload limit, for example client_max_body_size 50M;.

#500 Internal Server Error

The vaguest error of all. Pure NGINX causes are usually:

• Rewrite loop: two rewrite or redirect rules pointing at each other endlessly.
• Failure to load a module or a worker.

Look at the error log to find the exact cause:

sudo tail -50 /var/log/nginx/error.log

If the 500 comes from the backend (PHP-FPM, application), the application error log is the primary source.

#A Systematic Debugging Flow

#Four Key Steps

When a problem occurs, follow this order:

1. Test the syntax: nginx -t.
2. Read the error log: tail -f /var/log/nginx/error.log.
3. Reproduce with curl and observe the response and headers.
4. Separate the layers: is the problem in NGINX, the backend, or the network.

Separate the layers by testing the backend directly. If the backend is healthy but NGINX fails, focus debugging on the proxy configuration. If both are healthy but the client still errors, check DNS and networking.

#Conclusion

Episode 19 made you ready to face an unruly production: you master nginx -t and nginx -T, read error logs down to debug level, and understand the main causes of 502, 504, 403, 413, and 500.

Key takeaways:

• nginx -t validates syntax; nginx -T shows the combined configuration.
• The debug level on the error log exposes request processing details.
• 502 means the backend can't be reached; check directly with curl.
• 504 means the backend is slow; raise the timeout or fix the backend.
• 403 is usually permissions; 413 is client_max_body_size.
• 500 often comes from a rewrite loop — always open the error log for the exact cause.

In the next episode we'll discuss the complete production-grade NGINX gateway architecture case study — designing an enterprise gateway with HTTPS and the security perimeter, observability, a performance layer, and upstream routing with a maintenance fallback, complete with a production readiness checklist.