How to test Nginx configuration

Testing Nginx configuration before a reload catches broken directives, bad includes, and missing files while the current worker processes are still serving requests. That turns a live edit into a controlled checkpoint instead of a risky restart attempt.

The nginx binary provides -t to parse the main configuration file plus every included file, and the check also attempts to open files referenced by the configuration. When you need to confirm which snippets are actually loaded, -T performs the same validation and prints the effective configuration tree to standard output.

Examples below use the common packaged layout with /etc/nginx/nginx.conf as the main file and additional snippets under /etc/nginx/conf.d/ or /etc/nginx/sites-enabled/. A clean syntax test is still not a full runtime check: it does not prove certificates exist at the configured paths, that upstream services are reachable, or that the target virtual host is the one answering on the expected address.

1. Open a terminal with a user account that can run sudo.
2. Open the Nginx configuration file or virtual host file that you changed.

   $ sudoedit /etc/nginx/nginx.conf

   Common edit locations include /etc/nginx/nginx.conf, /etc/nginx/conf.d/, and /etc/nginx/sites-enabled/ depending on distribution packaging.

3. Print the loaded configuration tree when you need to confirm which file Nginx is reading.

   $ sudo nginx -T 2>/dev/null | grep -n 'configuration file '
   1:# configuration file /etc/nginx/nginx.conf:
   86:# configuration file /etc/nginx/mime.types:
   189:# configuration file /etc/nginx/conf.d/example.conf:

   nginx -T performs the same validation as nginx -t and also dumps the loaded configuration to standard output.

4. Run the Nginx configuration test.

   $ sudo nginx -t
   nginx: [emerg] unexpected "}" in /etc/nginx/conf.d/broken.conf:8
   nginx: configuration file /etc/nginx/nginx.conf test failed

   The first reported file and line are the fastest path to the actual parse failure.

5. Correct the directive, include, or file path identified by the failed test.
6. Re-run the configuration test until it reports a clean result.

   $ sudo nginx -t
   nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
   nginx: configuration file /etc/nginx/nginx.conf test is successful

   A clean test confirms syntax and referenced-file access, but it does not prove backend reachability, TLS file correctness at request time, or free listen ports.

7. Reload Nginx to apply the validated configuration without dropping active connections.

   $ sudo systemctl reload nginx

   Use sudo nginx -s reload on systems where systemd is not managing the service.

   Related: How to manage the Nginx service

8. Confirm that the Nginx unit stayed active after the reload.

   $ sudo systemctl is-active nginx
   active

   If the unit returns failed or inactive, inspect the journal before retrying the reload.

   Related: How to manage the Nginx service

9. Review recent unit log lines when the reload fails or the service does not stay active.

   $ sudo journalctl --unit=nginx.service --no-pager --lines=20

   Look for the lines immediately before the failure, because systemd usually records the failing command and exit status there.

   Related: How to audit Nginx access logs for security threats

10. Verify that the expected site still answers HTTP requests after the reload.

    $ curl -I -sS http://127.0.0.1/
    HTTP/1.1 200 OK
    Server: nginx/1.24.0 (Ubuntu)
    Date: Thu, 09 Apr 2026 12:55:10 GMT
    Content-Type: text/plain
    Content-Length: 16
    Connection: keep-alive

    Use the real site hostname or a matching Host header instead of 127.0.0.1 when the validated configuration serves a non-default virtual host.