Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

nginx does not start and says the configuration test failed

Errornginx: configuration file /etc/nginx/nginx.conf test failed

Short answer

The message 'test failed' is only the last line. The reason is the [emerg] line printed just above it. Run nginx -t as root, read that line, fix the file and line number it names, and test again before starting. The usual reasons are a syntax error, a file nginx cannot open, or testing a different config file.

  • Applies to nginx 1.26 and 1.28, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Test the config as root and read the first [emerg] line. It names the file and line to fix. The error log holds the same text.

    sudo nginx -t
    sudo tail -n 20 /var/log/nginx/error.log
  2. 2Match what you see, then jump to its fix

    1. 1[emerg] with a file name and a line number, such as an unexpected end of file or a missing semicolonA syntax error or unknown directive in a config fileFix
    2. 2[emerg] naming a certificate, include file, or log path, followed by No such file or directoryA file named in the config cannot be openedFix
    3. 3The test passes for the file you edited, but the service still failsYou tested a different config than the one the service startsFix

What does the error look like?

  • nginx: configuration file /etc/nginx/nginx.conf test failed
  • nginx: [emerg] ... followed by the file name and line number of the faulty directive

Cause 1 of 3

A syntax error or unknown directive in a config file

1Check

nginx -t checks syntax first. Dump everything that was loaded, including included files, and go to the line it named.

sudo nginx -T | sed -n '1,80p'

2Fix

Edit the named file and line. Common finds are a missing semicolon, an unbalanced brace, or a directive in the wrong block. Test again until it prints that the syntax is ok.

sudo nano /etc/nginx/sites-enabled/example.conf
sudo nginx -t

3Verify

Start the service and confirm it is active.

sudo systemctl start nginx
systemctl is-active nginx

Confirmed by nginx.org

Did this fix it?

Cause 2 of 3

A file named in the config cannot be opened

1Check

After the syntax check, -t tries to open files that the config refers to. Check the path from the message.

sudo nginx -t 2>&1 | head -n 5
sudo ls -l <path from the message>

2Fix

Create the missing file or folder, or remove the directive that points to it. For missing certificates see the page on the certificate file error.

sudo mkdir -p /var/log/nginx

3Verify

The test now ends with the 'test is successful' line.

sudo nginx -t

Confirmed by nginx.org

Did this fix it?

Cause 3 of 3

You tested a different config than the one the service starts

1Check

The main file is nginx.conf in /usr/local/nginx/conf, /etc/nginx or /usr/local/etc/nginx, depending on the build, and -c selects another file. A test run with -c does not test the default one.

sudo nginx -t

2Fix

Test without -c, so you test the file the service loads, or test the exact file with -c and make the service use that same file.

sudo nginx -t -c /etc/nginx/nginx.conf

3Verify

Both the plain test and the service start agree.

sudo nginx -t && sudo systemctl restart nginx

Confirmed by nginx.org

Did this fix it?

How do I stop it coming back?

  • Run nginx -t before every reload or restart; a reload with a bad config keeps the old one running.
  • Change one thing at a time so the failing line is obvious.
  • Keep nginx.conf and site files in version control.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.