How to Test Your NGINX Configuration Before Screwing it Up

Ravgeet Dhillon

Read more posts by this author.

We’ve all been there; you need to make “just this one little change” to your NGINX configuration and before you know it, your web server is down. Fortunately, there’s an answer in NGINX, test config changes!

There are several tasks you can perform to test config changes in NGINX with built-in switches, troubleshooting best practices, and testing permissions. In this tutorial, you’re going to learn how to get started ensuring you never take production down again!

Validating NGINX Configuration File Syntax

NGINX configuration files follow a specific schema. You can’t just provide any text in a configuration file and expect NGINX to understand it. You need to test it’s syntax first before releasing it into an important environment.

To test an NGINX config file, the nginx binary provides the -t switch. The -t switch is a flag that tells NGINX to read the config file (and all files referenced in the main config file) and ensure the syntax is valid.

sudo nginx -t

The -t switch not only tests syntax in the main NGINX config file, but it also reads and tests syntax for all files referenced via an include statement also.

If the syntax of the configuration file is valid, you’ll see the following:

NGINX Configuration Test is Successful
NGINX Configuration Test is Successful

On the contrary, you’ll see below that if you’ve made a mistake in the config file, the -t switch will tell you.

NGINX Configuration Error
NGINX Configuration Error

If, for example, NGINX can’t read an included file in the config file due to a permission problem, you’ll see the below output.

Permissions Error in the Included file.
Permissions Error in the Included file.


You should now know how to use NGINX to test config file syntax! When you make a change to an NGINX config file, remember to always run the -t switch!

Subscribe to Stay in Touch

Never miss out on your favorite ATA posts and our latest announcements!

Looks like you're offline!