Debug mode in Nginx - Commands & Configuration

Introduction

Sometimes your web server has problems and you need to find out what is wrong. Debug mode in nginx helps by showing detailed information about what the server is doing. This makes it easier to fix issues.

When your website is not loading and you want to see detailed error messages.

When you want to check how nginx processes requests step-by-step.

When you need to find configuration mistakes causing server errors.

When you want to monitor how nginx handles connections and responses.

When troubleshooting slow responses or unexpected behavior in nginx.

Config File - nginx.conf

nginx.conf

worker_processes  1;

events {
    worker_connections  1024;
}

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

    server {
        listen       80;
        server_name  localhost;

        location / {
            root   /usr/share/nginx/html;
            index  index.html index.htm;
        }
    }
}

This configuration sets nginx to run with one worker process and allows 1024 connections. The key part is error_log /var/log/nginx/error.log debug; which enables debug mode for error logging. This means nginx will write detailed debug information to the error log file. The server block listens on port 80 and serves files from the default html folder.

Commands

This command tests the nginx configuration file for syntax errors before applying it. It helps ensure the config is valid.

Terminal

sudo nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

This command restarts the nginx service to apply the new configuration with debug mode enabled.

Terminal

sudo systemctl restart nginx

Expected Output

No output (command runs silently)

This command shows the live debug logs from nginx error log file. You can watch detailed debug messages as requests come in.

Terminal

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

Expected Output

2024/06/01 12:00:00 [debug] 12345#0: *1 http request line: "GET / HTTP/1.1"

2024/06/01 12:00:00 [debug] 12345#0: *1 http uri: "/"

2024/06/01 12:00:00 [debug] 12345#0: *1 http args: ""

Key Concept

If you remember nothing else from this pattern, remember: enabling debug mode in nginx means setting the error_log level to debug to get detailed logs.

Common Mistakes

Not testing the nginx configuration before restarting the service.

If the config has errors, nginx will fail to start and your website will be down.

Always run 'sudo nginx -t' to check the config syntax before restarting nginx.

Forgetting to restart nginx after changing the configuration.

Changes in the config file do not take effect until nginx is restarted or reloaded.

Run 'sudo systemctl restart nginx' or 'sudo nginx -s reload' after config changes.

Not checking the correct error log file for debug messages.

Debug messages only appear in the error log file set with debug level, missing them means no useful info.

Verify the error_log path and level in nginx.conf and check that file for debug output.

Summary

Set the error_log directive with debug level in nginx.conf to enable debug mode.

Test the configuration with 'nginx -t' before restarting nginx.

Restart nginx to apply changes and use 'tail -f' on the error log to see debug messages.