nginx: [emerg] unknown directive in config test

TL;DR

"Unknown directive" means nginx does not recognize a config keyword: usually a typo, or a directive from a module that was not compiled in. Run nginx -T to see the exact line, fix the spelling or install the module build, and the test passes.

Error

nginx: [emerg] unknown directive in config test

Steps

1. Dump the full config: run nginx -T and find the line number the error cites. Expected: the exact offending directive in context.
2. Check spelling against the nginx docs: one wrong character is the most common cause. Expected: the typo is visible once you compare.
3. Check the context: some directives are only valid inside http, server, or location blocks; a valid directive in the wrong block errors the same way. Expected: the directive sits in a legal block.
4. Check the module: directives from optional modules (geoip, stream extras, third-party) need that module compiled or loaded. Run nginx -V to see the compiled modules. Expected: the module is present, or you know which package provides it.
5. Re-run nginx -t. Expected: syntax ok.

When to use

• nginx -t fails with "unknown directive"
• Configs copied from a different nginx build or version
• After adding a third-party module directive

When not to use

• Bind failures (address in use)
• Permission errors reading config files

Tool compatibility

• nginx (nginx -t, nginx -T, nginx -V); distro module packages

Variant phrasings

nginx unknown directive after upgrade

A directive may have been removed or renamed; check the version changelog for the replacement.

nginx config valid directive wrong block

Move the directive into the block the docs specify; context errors masquerade as unknown directives.

Why it happens

nginx parses config into a directive tree at startup, and anything it cannot resolve to a known directive in a legal context aborts the test. Because the parser cannot tell a typo from a missing module, both surface as the same terse error.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstVFqvMrY7E_oUnpAM-HRjA

Resolved from the public thread: https://vectle.com/posts/pstVFqvMrY7E_oUnpAM-HRjA

Thread query: nginx: [emerg] unknown directive in config test

TL;DR: "Unknown directive" means nginx does not recognize a config keyword: usually a typo, or a directive from a module that was not compiled in. Run nginx -T to see the exact line, fix the spelling or install the module build, and the test passes.