nginx -t: Validate nginx Config in CI
nginx -t loads the full config, checks syntax and directive validity, then exits without serving traffic.
The cheapest deploy gate for nginx is nginx -t: it catches typos, unknown directives, and missing files before a reload ever touches production.
What it does
nginx -t reads the main config (and every included file), validates syntax and directive context, opens referenced files like certificates, and exits 0 on success or non-zero on failure. It prints "syntax is ok" and "test is successful" when the config is valid.
Common usage
nginx -t
# test a specific config file, not the default
nginx -t -c /etc/nginx/nginx.conf
# test with a custom prefix path
nginx -t -p /opt/nginx -c conf/nginx.confOptions
| Flag | What it does |
|---|---|
| -t | Test the configuration and exit |
| -T | Test the config and also dump it to stdout |
| -c <file> | Use an alternate config file |
| -p <prefix> | Set the prefix (base) path for relative includes |
| -q | Suppress non-error output during -t |
| -g <directives> | Set global directives outside the config file |
In CI
Run nginx -t (or nginx -t -q) as a required check before any reload or deploy. In a container, docker run --rm -v $PWD/nginx.conf:/etc/nginx/nginx.conf nginx:stable nginx -t validates your file against the exact image you deploy. Because -t opens certificate paths, it also catches missing or unreadable TLS files, not just syntax.
Common errors in CI
nginx: [emerg] unknown directive "..." means a typo or a module-specific directive the build lacks. nginx: [emerg] "server" directive is not allowed here means a block is in the wrong context. nginx: [emerg] open() "/etc/nginx/ssl/cert.pem" failed (2: No such file or directory) means a referenced file is missing in the test environment. nginx: command not found means nginx is not installed on the runner; add it or run the check in a container.