How to troubleshoot Nginx?

Even if we using Nginx as a web server with our utmost care, we may also encounter all kinds of issues, ranging from simple configuration errors to the occasional unexpected behavior of one module or another. In these cases, we need some useful solutions for troubleshooting Nginx.

Nginx checking access permissions

A lot of errors are caused by invalid access permissions. In which case, we can specify a user and group for the Nginx worker processes to run: build with the configure command, or specify them with the user directive in the configuration file.

Nginx testing configuration

If the configuration file contains syntax or semantic errors, the application will refuse to reload. Even worse, if Nginx is stopped (e.g.: after a complete server reboot) it will refuse to start at all.

  1. Always keep a backup of working configuration files in case something goes wrong
  2. Before reloading or restarting Nginx, test the configuration: nginx -t -c ../conf/nginx_candidate.conf

Nginx reload service

Unlike Apache, Nginx does not support on-the-fly configuration changes in .htaccess files or similar. So take a moment to make sure you did reload Nginx: nginx -s reload. Why not restart? Reload will keep existing connections alive and thus won't interrupt ongoing file downloads.

Nginx analyzing logs

There are three variations of log files you may want to check:

  1. Check the error logs. Depending on the level you defined, Nginx will provide details on its inner functioning. 
  2. Check the access logs. These contains information about requests themselves: the request method, URI, the HTTP respons, and more, depending on the log format you defined. 
  3. Check the debug logs. To activate debug logging, the nginx binary needs to have been compiled with the --with-debug configure flag. As this flag is not recommended for high performance production systems, we may want to provide two separate nginx binaries for our needs: one which we use on production, and one that has all the same configure options used on dev or beta.

Nginx 400 Bad Request

Occasionally, Nginx returns 400 Bad Request error pages to visitors. Most of the time this is when cookie data exceeds a certain size. In order to prevent further trouble, you may simply increase the value of the large_client_header_buffers directive in order to allow larger cookie data size.

Nginx location priorities

The problem frequently occurs when using multiple location blocks in the same server block: configuration does not apply as you thought it would.

Share this Post