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
- Fix on Debian and Ubuntu
- Which line needs which module
- Why each fix shows a new error
- "Syntax OK", but every page is a 500
- The <IfModule> trap
- RHEL, AlmaLinux, Rocky
- The official httpd Docker image
- In .htaccess
- Check which modules are on
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 config | Module | What happened without it |
|---|---|---|
ProxyPass, ProxyPassReverse, ProxyPreserveHost | proxy | Invalid command, Apache won't start |
ProxyPass to an http:// app | proxy_http | Syntax OK, then every request is a 500 (see below) |
RequestHeader | headers | Invalid command 'RequestHeader' |
RewriteEngine, RewriteRule | rewrite | Invalid command 'RewriteEngine' |
SSLEngine, SSLCertificateFile | ssl | Invalid command 'SSLEngine' |
Protocols h2 http/1.1 | http2 | No 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 far | What configtest said |
|---|---|
| None | Invalid command 'RewriteEngine' |
rewrite | Invalid command 'SSLEngine' |
rewrite, ssl | Invalid command 'ProxyPreserveHost' |
… proxy, proxy_http | Invalid command 'RequestHeader' |
… headers | Syntax 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