Apache “Invalid command 'ProxyPass'”: turn on the proxy modules

Updated 18 November 2026 · By Brent Alexis

Short answer: Apache doesn't know ProxyPass until the module that defines it is loaded. On Debian and Ubuntu, run sudo a2enmod proxy proxy_http headers, test with sudo apache2ctl configtest, then restart Apache. The same error with ProxyPreserveHost, RequestHeader, RewriteEngine or SSLEngine means the same thing: a module is off. Turn them all on in one go, not one per error.

Tested on the official httpd Docker image (Apache 2.4.71), Debian 12's Apache 2.4.71 and AlmaLinux 9's Apache 2.4.62, with ProxyForge's own virtual host output and a small test app that reports what it receives: 34 checks. How it's tested

The error, word for word

This is what Debian 12 printed for a reverse proxy virtual host from the Config Generator, on a fresh install with nothing extra turned on:

$ sudo apache2ctl configtest
AH00526: Syntax error on line 10 of /etc/apache2/sites-enabled/example.com.conf:
Invalid command 'ProxyPreserveHost', perhaps misspelled or defined by a module not included in the server configuration
Action 'configtest' failed.
The Apache error log may have more information.

Notice it names ProxyPreserveHost, not ProxyPass. Apache stops at the first line it doesn't recognise, and in most proxy configs that's whichever proxy line comes first. With only the ProxyPass lines in the file, the message was Invalid command 'ProxyPass', same wording. Apache refuses to start while this error is there.

Fix on Debian and Ubuntu

This is the virtual host the generator writes for a reverse proxy (HTTPS, Gzip and WebSockets unticked). Its comment lines already list the modules it needs:

# Generated Apache virtual host — review paths before deploying
# Save as /etc/apache2/sites-available/example.com.conf (Debian/Ubuntu, then: sudo a2ensite example.com)
# or /etc/httpd/conf.d/example.com.conf (RHEL, Alma, Rocky, Fedora).
# Needs these modules: proxy, proxy_http, headers. Debian/Ubuntu: sudo a2enmod proxy proxy_http headers

<VirtualHost *:80>
    ServerName example.com
    ServerAlias www.example.com

    ProxyPreserveHost On
    RequestHeader set X-Forwarded-Proto "http"
    ProxyPass / http://127.0.0.1:3000/
    ProxyPassReverse / http://127.0.0.1:3000/
</VirtualHost>

Turn the modules on, test, then restart:

sudo a2enmod proxy proxy_http headers
sudo apache2ctl configtest
sudo systemctl restart apache2

After that, configtest said Syntax OK and requests reached the app. a2enmod itself ends by telling you to restart Apache, so restart rather than reload. Debian 12 was tested; Ubuntu uses the same a2enmod tool.

On a fresh Debian 12, none of these modules were on: proxy, proxy_http, headers, rewrite, ssl and http2 were all off. Only deflate was already on.

Which line needs which module

Line in your configModuleWhat happened without it
ProxyPass, ProxyPassReverse, ProxyPreserveHostproxyInvalid command, Apache won't start
ProxyPass to an http:// appproxy_httpSyntax OK, then every request is a 500 (see below)
RequestHeaderheadersInvalid command 'RequestHeader'
RewriteEngine, RewriteRulerewriteInvalid command 'RewriteEngine'
SSLEngine, SSLCertificateFilesslInvalid command 'SSLEngine'
Protocols h2 http/1.1http2No error at all: Syntax OK, and the site just doesn't use HTTP/2

a2enmod proxy_http turns on proxy for you. It printed Considering dependency proxy for proxy_http and enabled both.

Why each fix shows a new error

Apache reports one unknown line at a time, so fixing modules one error at a time takes several rounds. With the generator's default output (HTTPS, Gzip and WebSockets ticked) on a fresh Debian 12, turning on one module after each error went like this:

Modules turned on so farWhat configtest said
NoneInvalid command 'RewriteEngine'
rewriteInvalid command 'SSLEngine'
rewrite, sslInvalid command 'ProxyPreserveHost'
… proxy, proxy_httpInvalid command 'RequestHeader'
… headersSyntax OK

The single line from the generator's comment, sudo a2enmod proxy proxy_http headers rewrite ssl http2 deflate, took the same fresh server straight to Syntax OK. Copy that line from your own output: it changes with the options you tick.

"Syntax OK", but every page is a 500

With proxy on but proxy_http off, the syntax check passed, Apache started, and every request got 500 Internal Server Error. The error log said why:

[proxy:warn] AH01144: No protocol handler was valid for the URL / (scheme 'http'). If you are using a DSO version of mod_proxy, make sure the proxy submodules are included in the configuration using LoadModule.

proxy only teaches Apache the ProxyPass line. Talking to an http:// app is proxy_http's job. Turn both on.

The <IfModule> trap

Some example configs wrap the proxy lines in <IfModule mod_proxy.c>. With mod_proxy off, that hides the error completely: httpd -t said Syntax OK with no warning, Apache started, and visitors got Apache's own “It works!” page. The app was never contacted. If your site shows the default Apache page instead of your app, check for this before anything else.

RHEL, AlmaLinux, Rocky

On AlmaLinux 9, the httpd package loads proxy and proxy_http by default from /etc/httpd/conf.modules.d/00-proxy.conf, and headers was loaded too. The generator's virtual host passed httpd -t and worked with no changes. There is no a2enmod on these systems.

So on the RHEL family, this error usually means someone edited conf.modules.d. Commenting out the proxy_module line didn't even give the “Invalid command” message; Apache stopped earlier, because other proxy modules in the same file depend on it:

Cannot load modules/mod_proxy_ajp.so into server: /etc/httpd/modules/mod_proxy_ajp.so: undefined symbol: proxy_module

Fix: restore the LoadModule lines in 00-proxy.conf, then sudo httpd -t and sudo systemctl restart httpd.

The official httpd Docker image

The official httpd:2.4 image ships with both proxy lines commented out in conf/httpd.conf (headers is already on):

#LoadModule proxy_module modules/mod_proxy.so
#LoadModule proxy_http_module modules/mod_proxy_http.so

Remove the # from both lines in your copy of httpd.conf. With them on, httpd -t passed and requests reached the app.

In .htaccess

A ProxyPass line in .htaccess with mod_proxy off doesn't stop Apache from starting. Instead, every page under that folder returns 500, and the error log names the file:

[core:alert] ... /usr/local/apache2/htdocs/.htaccess: Invalid command 'ProxyPass', perhaps misspelled or defined by a module not included in the server configuration

Turning the module on doesn't fix it here: the message changes to ProxyPass not allowed here, because ProxyPass never works in .htaccess. See ProxyPass not allowed in .htaccess for the options.

Check which modules are on

sudo apache2ctl -M | grep -E 'proxy|headers'   # Debian/Ubuntu
sudo httpd -M | grep -E 'proxy|headers'        # RHEL, AlmaLinux, Rocky

You should see proxy_module, proxy_http_module and headers_module in the list. Then run the syntax test again and restart Apache.

Generate an Apache virtual host with the module list built in →

How to use ProxyForge · FAQ: common errors · Guides · What's new · About