Check Apache Config Syntax: apache2ctl -t, httpd -t and Common Errors

This article is a localized edition of the Japanese original. Read the Japanese original

If you restart Apache with a mistake in its configuration files, Apache cannot start and the whole site goes offline. Whenever you change the configuration, check the syntax before applying it.

This article covers the syntax check commands and how common errors look and how to fix them. The commands and error messages were verified as of October 2026 on Apache 2.4.67 on Debian 13.

Syntax check commands

The command names differ between Debian/Ubuntu and the RHEL family (AlmaLinux, Rocky Linux and others).

If there is no problem, Syntax OK is printed at the end.

sudo apache2ctl -t

Syntax OK

You may also see the following line. It is a warning, not an error. As long as Syntax OK appears, the syntax is correct and you can apply the change.

AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 172.17.0.6. Set the 'ServerName' directive globally to suppress this message

To get rid of this warning, add a single ServerName line (for example ServerName www.example.com) to /etc/apache2/apache2.conf (/etc/httpd/conf/httpd.conf on the RHEL family).

Find the configuration files

On Debian and Ubuntu, dedicated commands enable and disable configurations and modules.

sudo a2ensite example.conf      # Enable sites-available/example.conf
sudo a2dissite 000-default.conf # Disable a site
sudo a2enmod rewrite            # Enable a module
sudo a2enconf remoteip          # Enable a configuration from conf-available

To see which files are actually loaded, use -t -D DUMP_INCLUDES. The number in parentheses is the line that includes that file.

Included configuration files:
  (*) /etc/apache2/apache2.conf
    (146) /etc/apache2/mods-enabled/access_compat.load
    (146) /etc/apache2/mods-enabled/alias.load

To see in which file and on which line each VirtualHost is defined, and which port it listens on, use -S.

VirtualHost configuration:
*:80                   172.17.0.6 (/etc/apache2/sites-enabled/000-default.conf:1)
ServerRoot: "/etc/apache2"
Main DocumentRoot: "/var/www/html"
Main ErrorLog: "/var/log/apache2/error.log"

Common errors and how to fix them

On an error, Apache shows which file and which line caused it. The messages below are what apache2ctl -t printed when each mistake was actually introduced.

A closing tag is missing

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/html

apache2: Syntax error on line 225 of /etc/apache2/apache2.conf: Syntax error on line 1 of /etc/apache2/sites-enabled/test1.conf: /etc/apache2/sites-enabled/test1.conf:1: <VirtualHost> was not closed.

The first part, line 225 of /etc/apache2/apache2.conf, is the line that includes the file. The real cause is in the file named after it: the <VirtualHost> on line 1 of test1.conf is never closed. Add </VirtualHost> at the end. A missing close for <IfModule> or <Directory> is reported the same way.

A directive is misspelled

<VirtualHost *:80>
    ServerNmae example.com
    DocumentRoot /var/www/html
</VirtualHost>

AH00526: Syntax error on line 2 of /etc/apache2/sites-enabled/test2.conf:
Invalid command 'ServerNmae', perhaps misspelled or defined by a module not included in the server configuration

Change ServerNmae to ServerName.

A module is not loaded

Even with the correct spelling, you get the same Invalid command if the module that provides the directive is disabled. For example, writing RewriteEngine while mod_rewrite is disabled produces this:

AH00526: Syntax error on line 3 of /etc/apache2/sites-enabled/test6.conf:
Invalid command 'RewriteEngine', perhaps misspelled or defined by a module not included in the server configuration

Enable the module, then check again.

sudo a2enmod rewrite
sudo apache2ctl -M | grep rewrite
sudo apache2ctl -t

A file given to Include does not exist

Include /etc/apache2/conf.d/missing.conf

apache2: Syntax error on line 225 of /etc/apache2/apache2.conf: Syntax error on line 1 of /etc/apache2/sites-enabled/test3.conf: Could not open configuration file /etc/apache2/conf.d/missing.conf: No such file or directory

Fix the file path, or use IncludeOptional if the file may legitimately be absent. IncludeOptional does not raise an error when no matching file exists (in this example the result was Syntax OK).

IncludeOptional /etc/apache2/conf.d/*.conf

The SSL certificate file does not exist

In a VirtualHost that uses mod_ssl, a missing file in SSLCertificateFile or similar directives is also reported as an error at the syntax check stage.

AH00526: Syntax error on line 5 of /etc/apache2/sites-enabled/test5.conf:
SSLCertificateFile: file '/etc/ssl/certs/notexist.pem' does not exist or is empty

Check the certificate path. If you use a Let's Encrypt certificate, make sure you point to files under /etc/letsencrypt/live/your-domain/.

What the syntax check cannot tell you

Syntax OK means the configuration is written correctly. It does not confirm that the settings do what you intend.

• If the DocumentRoot directory does not exist, you get the warning AH00112: Warning: DocumentRoot [/var/www/notexist] does not exist, but the result is still Syntax OK. Read the warning lines too
• Check duplicate ServerName values and which VirtualHost becomes the default in the -S listing
• Confirm that redirects and access restrictions work as intended after applying, with curl -I or similar

A safe procedure for applying changes

Change the configuration in this order:

# 1. Keep a copy of the file before the change
sudo cp /etc/apache2/sites-available/example.conf /etc/apache2/sites-available/example.conf.bak-$(date +%Y%m%d)

# 2. Edit the configuration
sudo nano /etc/apache2/sites-available/example.conf

# 3. Check the syntax
sudo apache2ctl -t

# 4. If Syntax OK, apply it (reloads the configuration after in-flight requests finish)
sudo systemctl reload apache2

# 5. Check the site and the error log
curl -I http://localhost/
sudo tail -n 50 /var/log/apache2/error.log

The copy is kept in sites-available/, but it is not loaded unless it is linked into sites-enabled/. In /etc/httpd/conf.d/ on the RHEL family, every file named *.conf is loaded, so give the copy a name that does not end in .conf (such as the .bak-date name in the example) or keep it in another directory.

The difference between reload and restart:

• systemctl reload apache2 runs apachectl graceful on Debian and Ubuntu. It switches to the new configuration after in-flight requests finish, so connections are not cut off. Debian's apache2ctl also runs a syntax check before graceful and restart, and if there is an error it prints the error instead of restarting
• systemctl restart apache2 stops Apache and then starts it. If the configuration has an error, Apache stays stopped and the site goes offline

In either case, run the syntax check in step 3 first.

When you apply changes from a script, make it stop if the syntax check fails.

#!/bin/bash
if ! apache2ctl -t; then
    echo "Syntax error: reload aborted" >&2
    exit 1
fi
systemctl reload apache2

Keep a history of configuration changes

Managing the configuration files with Git lets you see what changed and when, and makes it easier to roll back a bad change.

cd /etc/apache2
sudo git config --global user.name "admin"            # First time only. Name recorded in commits
sudo git config --global user.email "admin@example.com"
sudo git init
sudo git add apache2.conf ports.conf sites-available/ conf-available/
sudo git commit -m "initial apache config"

# After a change, review the diff, then record it
sudo git diff
sudo git commit -am "add example.com vhost"

Summary

• After changing the configuration, run apache2ctl -t (httpd -t on the RHEL family) before applying it, and confirm Syntax OK
• Errors show the file name and line number of the cause. When the cause is in a file loaded with Include, look at the file and line given at the end of the message
• Invalid command means either a typo or a disabled module
• Use -S for the VirtualHost list, -M for modules and -t -D DUMP_INCLUDES for loaded files
• Apply changes with systemctl reload. With restart, a configuration error leaves Apache stopped

Related articles:

• How to restart and reload Apache
• How to find out why Apache will not start
• How to set up Apache VirtualHosts
• How to test Nginx configuration files

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)