🚨 NGINX Error Guide: 'invalid number of arguments in directive' — Fix Config Syntax

Overview

NGINX refuses to start or reload and prints this during config parsing (nginx -t) when a directive receives the wrong number of arguments. The message names the directive and the file/line:

nginx: [emerg] invalid number of arguments in "add_header" directive in /etc/nginx/conf.d/site.conf:42

Because NGINX tokenizes on whitespace, the count is almost never about the directive being “wrong” conceptually — it’s about how many space-separated tokens NGINX saw. A missing semicolon, an unquoted value containing spaces, or a stray token changes the count and trips this error.

Symptoms

• nginx -t fails with [emerg] invalid number of arguments in "<directive>" directive and a file:line reference.
• systemctl reload nginx fails and the old workers keep serving the previous config (a reload safety feature).
• The named line looks “correct” at a glance — the real problem is often the line above (missing ;) or a value with unquoted spaces.
• The error started right after editing that file or pasting a snippet from documentation.

Common Root Causes

• Missing semicolon on the previous line — NGINX runs two directives together, so the named directive appears to have extra arguments.
• Unquoted value containing spaces — e.g. add_header Content-Security-Policy default-src 'self'; where the policy has spaces; without quotes NGINX counts each token as a separate argument.
• Wrong argument count for the directive — e.g. return 301 with no URL, rewrite missing its replacement, or log_format name/string mismatch.
• A variable that expands to multiple tokens — a set $x "a b"; used unquoted downstream.
• Copy-paste artifacts — a smart-quote, a non-breaking space, or a line break inside what should be one value.

Diagnostic Workflow

Let nginx -t point you at the file and line, then inspect it and the line above:

nginx -t

nginx: [emerg] invalid number of arguments in "add_header" directive in /etc/nginx/conf.d/site.conf:42

Open the file at that line and check three things: the semicolon on the line above, whether the value has unquoted spaces, and whether hidden characters snuck in:

# Show the offending line with surrounding context and visible line endings
sed -n '38,44p' /etc/nginx/conf.d/site.conf | cat -A

The typical culprit — a header value with spaces that must be a single quoted argument:

# WRONG: NGINX sees 4+ arguments after the header name
add_header Content-Security-Policy default-src 'self'; script-src 'self';

# CORRECT: the whole policy is ONE quoted value; use 'always' as the optional 3rd arg
add_header Content-Security-Policy "default-src 'self'; script-src 'self'" always;

Another common one — a missing semicolon merging two directives:

# WRONG: no ';' after the root, so NGINX reads "index" as an extra arg to root
root /var/www/site
index index.html;

# CORRECT
root /var/www/site;
index index.html;

Validate after each fix:

nginx -t && nginx -s reload

Example Root Cause Analysis

An engineer added a Content-Security-Policy header and every reload failed with invalid number of arguments in "add_header" directive ... :42. Line 42 looked fine in isolation. The problem was that the CSP value contained spaces and semicolons but was not quoted, so NGINX tokenized default-src, 'self';, script-src, and 'self'; as four-plus separate arguments to add_header, which accepts a header name, one value, and an optional flag.

Wrapping the entire policy in double quotes turned it into a single value argument: add_header Content-Security-Policy "default-src 'self'; script-src 'self'" always;. nginx -t passed immediately. Running the line through cat -A also revealed the internal ; characters that had been prematurely ending the directive — a reminder that inside NGINX config, a ; is a statement terminator unless it’s inside a quoted string.

Prevention Best Practices

• Always quote any directive value that contains spaces, semicolons, or special characters — CSP headers, log formats, and map values especially.
• After every edit, run nginx -t before reloading; a reload with a bad config is safe (old workers persist), but catching it in -t is faster than debugging live.
• When the named line looks correct, check the line ABOVE for a missing semicolon first — it’s the most common cause.
• Use cat -A (or grep -P '\t') to surface smart quotes, non-breaking spaces, and stray tabs from copy-pasted snippets.
• Keep complex header/log values in a dedicated include file so they’re easy to review and quote consistently.
• Prefer an editor with NGINX syntax highlighting so unterminated strings and missing semicolons are visible before you save.

Quick Command Reference

# Identify the file and line
nginx -t

# Inspect the line and its neighbor, revealing hidden characters
sed -n 'START,ENDp' /path/to/conf | cat -A

# Search for likely unquoted multi-token values
grep -rn "add_header .* .* .*;" /etc/nginx/

# Validate and reload after fixing
nginx -t && nginx -s reload

Conclusion

invalid number of arguments in directive is a tokenization error: NGINX counted more or fewer space-separated arguments than the directive allows. The fix is almost always to quote a value that contains spaces or to add a missing semicolon on the preceding line. Trust the file:line that nginx -t gives you, inspect the line above it, reveal hidden characters with cat -A, and re-run nginx -t until it passes before reloading.