nginx: configuration file test failed - finding the syntax error

An nginx -t or nginx -s reload ending with nginx: configuration file /path/to/nginx.conf test failed means the configuration tree is syntactically invalid or references a missing file. The master process rejects the change, so the running server continues with the previous working configuration. That prevents an outage, but your intended change is silently inactive. Read the exact error message, map it to the real source, fix it, and validate with nginx -t before reloading.

These failures typically surface after editing site files, rotating SSL certificates, or deploying auto-generated fragments. The error format is predictable: nginx: [emerg] <description> in <file>:<line>. That file:line pair is the starting point, though the root cause often sits on the preceding line or in an included file.

What this means

When you run nginx -t, the master process parses the configuration as it would during startup or reload. On success it prints:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: the configuration file /etc/nginx/nginx.conf test is successful

It returns exit code 0. On failure it prints something like:

nginx: [emerg] unknown directive "foo" in /etc/nginx/conf.d/site.conf:12

It returns exit code 1.

The nginx -T flag validates and dumps the fully merged configuration to stdout. Use it when include directives pull in dozens of files and you need to see the final parsed structure. Both flags accept -c <path> for non-default locations. The -q flag suppresses success text, returning silently unless an error exists; use it in automation.

Because nginx validates before applying, a failed reload via nginx -s reload or HUP leaves old workers intact. The master PID does not change. Old workers continue serving existing connections until they drain, but no new workers spawn with the broken config. The service stays up, but the intended change is absent.

Missing SSL certificate files are caught at nginx -t time. Since nginx 1.25.1, the deprecated standalone ssl directive is removed; using it produces an [emerg] unknown directive "ssl" error at test time.

Common causes

Quick checks

Run these before editing anything. They are read-only and safe.

# Test syntax and print the fully merged configuration tree
nginx -T

# Test syntax quietly: exits 0 on success, prints only errors
nginx -t -q

# Test a non-default configuration path explicitly
nginx -t -c /etc/nginx/nginx.conf

# Verify which HTTP modules are compiled in
nginx -V 2>&1 | grep with-http_

# Check for non-ASCII bytes at the start of the main config (BOM)
od -c /etc/nginx/nginx.conf | head -1

# List include directives to spot bare directory paths
grep -n 'include' /etc/nginx/nginx.conf

# Verify the master process is alive and responsive
kill -0 $(cat /var/run/nginx.pid) 2>/dev/null && echo "master alive"

# Count worker processes
pgrep -c -P $(cat /var/run/nginx.pid)

# Review recent error log entries for reload or test events
tail -100 /var/log/nginx/error.log | grep -E 'test failed|reconfiguring'

How to diagnose it

flowchart TD
    A[nginx -t fails] --> B{Error type?}
    B -->|unknown directive| C[Check nginx -V for module
and load_module context]
    B -->|unexpected end of file| D[Check prior line for missing ;
or unbalanced brace]
    B -->|Is a directory| E[Fix include path to use *.conf wildcard]
    B -->|certificate not found| F[Verify ssl_certificate path]
    B -->|garbled line number| G[Check file encoding for BOM]
    C --> H[Run nginx -t again]
    D --> H
    E --> H
    F --> H
    G --> H
    H -->|Success| I[Run nginx -s reload]
    H -->|Failure| B

1. Read the file:line in the [emerg] message. The parser reports where it became confused, not necessarily where the mistake was introduced. If line 12 is reported, inspect line 11 for a missing semicolon or an unclosed brace.
2. Run nginx -T and inspect the merged output. include directives can obscure the real sequence. The merged dump shows you exactly what nginx sees after all includes are resolved. Look for duplicate server blocks or directives that appear inside the wrong context.
3. If the error is unknown directive, check module availability. Run nginx -V to see compiled-in modules. For dynamic modules, verify the .so file exists and that load_module appears at the top level of nginx.conf, before any http block. Placing load_module inside http {} or server {} produces a context error.
4. Check include paths for bare directories. If the error is [crit] pread() ... failed (21: Is a directory), locate the include directive and change it to target files via a wildcard such as include /etc/nginx/conf.d/*.conf;.
5. Check for duplicate declarations. Including a file that contains a bare server {} block at the top level of http {} is fine. Including a file that opens a new http {} block inside an existing http {} block causes a parse error. Similarly, duplicate declarations in the same context can trigger emerg-level errors.
6. Inspect for encoding corruption. If the line number in the error message is obviously wrong or the directive text appears garbled, the file may carry a UTF-16LE BOM from a Windows editor. Use od -c to check for non-ASCII bytes at the start of the file. Convert with iconv -f UTF-16LE -t UTF-8 or dos2unix.
7. Validate SSL certificate paths. Missing certificate files are caught at nginx -t time. Confirm that ssl_certificate and ssl_certificate_key paths exist and are readable by the nginx process.
8. Avoid process substitution in shell. Passing <(cat file.conf) as the config argument to nginx -t causes a two-pass evaluation where the second pass finds the file gone, triggering a misleading failure. Always write to a real temporary file before testing.
9. Re-run nginx -t after each change. Do not issue nginx -s reload until the test returns exit code 0 and prints the success message.

Fixes

Missing terminator or unbalanced braces

Open the reported file and scan backward from the reported line. Every simple directive must end with a semicolon. Every block must open and close with braces. If the file is large, use nginx -T to see the fully merged tree; structural errors become obvious when indentation is consistent. Fix the terminator or brace, then re-test.

Unloaded dynamic module

If the directive requires a dynamic module, locate the .so file (commonly under /usr/lib/nginx/modules/ on Debian-based systems). Add the directive at the top level of nginx.conf:

load_module modules/ngx_http_js_module.so;

Do not place this inside http {} or server {}. A reload is sufficient; the module is loaded at configuration parsing time during the reload. After editing, run nginx -t.

Include path points to a directory

Replace any bare directory include with a wildcard pattern:

include /etc/nginx/conf.d/*.conf;

If you need to include files in subdirectories, use a wildcard that matches files, or list each file explicitly. nginx cannot read a directory as a configuration file.

Deprecated standalone ssl directive

Since nginx 1.25.1, remove ssl on; from your server blocks. Use the ssl parameter on the listen directive instead:

listen 443 ssl;

Setting ssl_certificate alone does not enable SSL for the socket.

Encoding corruption

Convert the file to plain UTF-8 without BOM. After conversion, run nginx -t immediately. If you manage configs in a repository, enforce .gitattributes or pre-commit hooks to reject UTF-16 or Windows line endings.

Duplicate declarations from include ordering

When splitting configuration across files, ensure that no file accidentally redeclares a block that its parent already opened. For example, if nginx.conf already contains http { include /etc/nginx/conf.d/*; }, the included files must not open another http {} block. The fix is to remove the nested block wrapper from the included file.

Failed reload with running service intact

If you attempted a reload and it failed, do not restart nginx. The previous configuration is still active and serving traffic. Fix the syntax error, validate with nginx -t, and only then run nginx -s reload. Avoid nginx -s stop or systemctl restart nginx while diagnosing, as that will drop active connections.

Prevention

• Gate deployments with nginx -t. Any script or configuration management tool that copies a new nginx config should run nginx -t -q before issuing nginx -s reload. If the test returns a non-zero exit code, stop the deployment and surface the error.
• Validate in CI before production. If your configuration is generated from templates, render it in a CI job and run nginx -t inside a container that matches your production nginx version. This catches version-specific directive removals, such as the ssl directive deprecation in 1.25.1.
• Audit merged config regularly. Run nginx -T and review the output for duplicate server names, overlapping listen directives, or directives that have migrated to the wrong context after refactoring.
• Keep load_module declarations centralized. Place all load_module lines at the top of nginx.conf, grouped together and commented. This prevents them from being accidentally moved inside a context block during edits.
• Standardize file encoding. Enforce UTF-8 without BOM in your editor configurations and repository hooks. Files edited on Windows should be converted before deployment.

Metrics and signals to monitor

How Netdata helps

• Correlate spikes in [emerg] and [crit] error log entries with reload events to detect failed deployments immediately.
• Track worker process count; sustained elevation above worker_processes signals stuck old workers after a successful reload.
• Track active connections and request rate to confirm service continuity while a configuration issue is being resolved.
• Monitor reload frequency to catch configuration management loops that repeatedly attempt invalid reloads.

Related guides

• How NGINX actually works in production: a mental model for operators
• nginx 413 Request Entity Too Large: client_max_body_size explained
• nginx 499 status code: why clients close connections before the response
• nginx 500 Internal Server Error: how to diagnose it
• nginx 502 Bad Gateway: causes and how to fix it
• nginx 503 Service Temporarily Unavailable: causes and fixes
• nginx 504 Gateway Time-out: causes and fixes
• NGINX active connections climbing: reading, writing, waiting explained
• NGINX backend cascade failure: when slow upstreams take down everything
• nginx: a client request body is buffered to a temporary file - what it means
• nginx connect() failed (111: Connection refused) while connecting to upstream
• NGINX connection exhaustion: detection, diagnosis, and prevention