nginx Debug Cheatsheet

nginx debugging commands.

Test config

nginx debug skills are essential for any team operating nginx in production. The cheatsheet covers the commands that come up repeatedly during operations and incident response. Knowing these saves time when minutes matter.

What testing config looks like:

• nginx -t validates the configuration.: The -t flag tests the configuration without applying. Syntax errors, missing files, invalid directives all surface; the team catches issues before they affect traffic.
• -T includes the full config.: nginx -T outputs the full effective configuration. Including all the includes, expanding all the variables. The output is what nginx is actually using; the team can verify the configuration is what they think it is.
• Run before reload.: nginx -t before nginx -s reload catches configuration errors. The test passes; the reload is safe; the production nginx does not crash on a bad config.
• CI integration.: Configuration tests in CI catch errors before they reach production. The team's nginx configuration changes go through the same review and test as application code.
• Common test patterns.: Test in staging; test with -t; test with -T; verify the output matches expectations. The discipline is testing thoroughly before production.

Testing the config is the foundation. Without it, configuration changes are gambles.

Reload

Reloading nginx is different from restarting. Reload preserves connections; restart drops them. The discipline is using reload for routine changes.

• nginx -s reload reloads config without dropping connections.: The reload signal tells nginx to re-read its configuration. Existing connections continue serving requests; new connections use the new configuration; the operation is graceful.
• Reload not equal to restart.: Restart stops and starts nginx; connections drop; users see disruption. Reload preserves connections; users see no disruption. For configuration changes, reload is correct.
• Test before reload.: The discipline is nginx -t followed by nginx -s reload. The test catches errors; the reload applies the change; the disruption is minimized.
• Worker process rotation.: nginx reload starts new workers with the new config; old workers finish their connections and exit. The transition is graceful; the discipline is built into nginx.
• Some changes need restart.: Major changes (binary upgrade, certain module changes) require restart. The team knows which is which; routine config changes use reload.

Reload is the routine operation. Knowing it is faster than restart matters when the disruption matters.

Logs

nginx logs are the primary debugging source. Configuration tells nginx what to log; the team's reading skills tell them how to interpret.

• error_log /var/log/nginx/error.log debug.: Setting error_log level to debug produces verbose output. Every connection, every redirect, every internal decision is logged.
• For verbose.: Debug logging is for investigation. The team turns it on when troubleshooting; the output is invaluable for understanding nginx's decisions.
• Don't leave on.: Debug logging is high volume. Leaving it on in production produces enormous logs; storage fills; performance degrades. Turn it on for investigation; turn it off when done.
• High volume.: Debug logs can be many gigabytes per hour. The team's logging infrastructure may not handle the volume; the cost is real.
• Conditional logging.: Some configurations support conditional debug logging (debug for specific clients, specific paths). The conditional approach gets the visibility without the full volume.

nginx debug cheatsheet is one of those operational skills that pays off in incident response. Nova AI Ops integrates with proxy and ingress telemetry, surfaces traffic patterns, and complements the local debug skills with cluster-wide visibility.