Apache proxy: No protocol handler was valid for the URL, what it means

AH01144: No protocol handler was valid for the URL means Apache's proxy found no module willing to talk to your backend. mod_proxy offered the backend URL to every proxy module that is loaded, and each one said no. Apache then answers 500 Internal Server Error. The usual reason is that the module for that kind of URL is not loaded. The word in (scheme '...') at the end of the line tells you which one: http needs mod_proxy_http, fcgi needs mod_proxy_fcgi, balancer needs mod_proxy_balancer. Load it with LoadModule, restart, and the 500 goes away.

Here is the full line from httpd 2.4.69, for a ProxyPass to fcgi://:

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

Two parts of it mislead people. /php/index.php is not the backend URL. It is the path the client asked for. And the scheme is not always the whole story: https can mean mod_ssl is missing, not a proxy module.

The rest of this page explains each row, how to make Apache tell you which module declined, and two cases that look like this error but are not.

What a protocol handler is, and what AH01144 says#

mod_proxy is the core of Apache's proxy. It reads ProxyPass and decides which requests to forward. It cannot speak to a backend on its own. That work is done by submodules, one per protocol: mod_proxy_http for HTTP, mod_proxy_fcgi for FastCGI, and so on. The mod_proxy manual lists them in a table and says "these additional modules will need to be loaded and configured".

The scheme is the part of the backend URL before ://. In ProxyPass "/app/" "http://app:8000/", the scheme is http. A protocol handler (the source calls it a scheme handler) is the function each submodule offers mod_proxy. When a request comes in, mod_proxy hands the backend URL to each loaded handler in turn. Each one looks at the scheme. It either takes the request or declines it.

AH01144 is what mod_proxy logs when every handler declined. In mod_proxy.c, the code sets the status to HTTP_INTERNAL_SERVER_ERROR right after it. That is the plain 500 page, not the "Proxy Error" page that other proxy failures produce. Nothing was sent to the backend. No connection was even tried.

The last sentence of the message is a hint: "If you are using a DSO version of mod_proxy, make sure the proxy submodules are included in the configuration using LoadModule." A DSO (dynamic shared object) is a module built as a separate .so file. The DSO page of the manual says modules "exist separately from the main httpd binary file". The official httpd image ships mod_proxy and each submodule as separate .so files, and so do the packages that use a2enmod. In that layout, each submodule needs its own LoadModule line.

The URL in the message is the client's path#

The format string reads No protocol handler was valid for the URL %s (scheme '%s'). In the 2.4.x source, the first value is r->uri, the path of the client's request. The second is the scheme of the backend URL. The 2.4.46 source uses the same two values, so this is not new.

In the test, a request for /app/x?q=1 logged for the URL /app/x (scheme 'http'). The query string was dropped, and the backend address appeared nowhere. To find the ProxyPass line at fault, match the path against your ProxyPass and RewriteRule prefixes, then read the scheme.

How the cases were checked#

Apache ran from the official httpd:2.4.69 and httpd:2.4.48 Docker images, each with the event MPM. Each case had its own minimal httpd.conf that loaded only the modules named in that case. curl sent the requests. No backend was needed for the AH01144 cases, since Apache never connects. The ws:// behavior of 2.4.46 and older was not run. That part comes from the tagged 2.4.46 source and the CHANGES file.

Both versions gave the same result for every case they shared. Each request that hit AH01144 got status 500.

Make Apache say which module declined#

AH01144 is logged at warn, so you see it at the default level. The lines that say why each handler declined are at debug. Turn them on for the proxy modules only. The core manual shows this per-module form, with LogLevel info ssl:warn as its example:

LogLevel warn proxy:debug proxy_http:debug

Then one failed request writes three lines:

[proxy:debug] mod_proxy.c(1467): AH01143: Running scheme fcgi handler (attempt 0)
[proxy_http:debug] mod_proxy_http.c(1901): AH01113: HTTP: declining URL fcgi://127.0.0.1:9000/var/www/index.php
[proxy:warn] AH01144: No protocol handler was valid for the URL /php/index.php (scheme 'fcgi'). ...

AH01143 shows the scheme mod_proxy is trying. AH01113 is mod_proxy_http saying "not mine", and it shows the full backend URL. That is the line to read when you have several ProxyPass lines and cannot tell which one matched.

proxy:debug alone is not enough. AH01112 and AH01113 come from mod_proxy_http, which logs under its own tag, proxy_http. With only proxy:debug, you see AH01143 and AH01144 but not the decline in between.

There is a trap here. If mod_proxy_http is not loaded, LogLevel ... proxy_http:debug stops Apache from starting. httpd 2.4.69 refused with Syntax error ... Cannot find module proxy_http. So when the scheme is http, use proxy:debug alone. In that case, no AH01113 line appears at all, and its absence is the answer: mod_proxy_http is not there to decline.

Turn the level back down when you are done. At debug, mod_proxy writes lines for every proxied request.

Cause 1: the module for the scheme is not loaded#

This is the cause in most cases. ProxyPass points at a scheme, and the module for it has no LoadModule line. Apache starts without complaint, because ProxyPass belongs to mod_proxy and mod_proxy is loaded. The failure only shows up per request.

The manual's table maps protocols to modules: HTTP to mod_proxy_http, FastCGI to mod_proxy_fcgi, HTTP/2 to mod_proxy_http2, AJP13 to mod_proxy_ajp, WebSockets to mod_proxy_wstunnel. It also lists mod_proxy_connect, mod_proxy_ftp, mod_proxy_scgi and mod_proxy_uwsgi. The test produced AH01144 with each of these schemes:

• http, with only mod_proxy loaded. There was no AH01113, since nothing was there to decline.
• fcgi, with mod_proxy_http loaded but not mod_proxy_fcgi.
• h2c, with mod_proxy_http loaded but not mod_proxy_http2. The mod_proxy_http2 source takes both h2 (HTTP/2 over TLS) and h2c (cleartext).

To fix it, check what is loaded:

apachectl -M | grep proxy

The httpd manual describes -M as "Dump a list of loaded Static and Shared Modules". Then add the missing line. The file names match the official image and a source build:

LoadModule proxy_module      modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule proxy_fcgi_module modules/mod_proxy_fcgi.so

On Debian and Ubuntu, the packaged layout uses a helper. Its manual page says a2enmod "is a script that enables the specified module within the apache2 configuration". Run a2enmod proxy_http (or proxy_fcgi, proxy_http2, proxy_ajp), then restart Apache.

Once the module is loaded, the request goes to the backend for the first time. If nothing listens there, the next error is a 503 with a failed connect. The http module logs that as AH01114, explained in why Apache returns 503 with AH01114. That is progress: the module now takes the request.

If mod_proxy itself is missing, you never get this far. httpd 2.4.69 refused to start with Invalid command 'ProxyPass', perhaps misspelled or defined by a module not included in the server configuration.

Cause 2: https:// with mod_ssl not loaded#

Here the scheme is https, and apachectl -M shows mod_proxy_http loaded. That looks impossible, since mod_proxy_http handles HTTPS. The debug line explains it:

[proxy_http:debug] AH01112: HTTP: declining URL https://10.9.9.9:8443/ (mod_ssl not configured?)
[proxy:warn] AH01144: No protocol handler was valid for the URL /api/ (scheme 'https'). ...

mod_proxy_http knows the https scheme, but it cannot do TLS itself. In the 2.4.x source, it first asks the core whether any module can secure an outgoing connection. That check, ap_ssl_has_outgoing_handlers() in server/ssl.c, is true once mod_ssl is loaded. If it is false, mod_proxy_http logs AH01112 and declines. With no other taker, mod_proxy logs AH01144.

AH01112 is a debug line. At the default level, you see only AH01144 with scheme https, which points at the wrong module. That is why this cause is hard to spot. The fix is LoadModule ssl_module modules/mod_ssl.so (on Debian, a2enmod ssl).

The two versions word AH01112 differently. 2.4.48 and 2.4.69 both logged HTTP: declining URL ... (mod_ssl not configured?). The 2.4.46 source has HTTPS: declining URL instead, so older logs may show that.

Loading mod_ssl is often not the end. mod_ssl is now there, but SSLProxyEngine is still off by default, so the next request fails with a different 500 and AH00961: https: failed to enable ssl support. That error and the certificate checks after it are in Apache ProxyPass to an HTTPS backend: AH00961. So AH01144 with scheme https means mod_ssl is not loaded. AH00961 means it is loaded but not turned on for the proxy.

Cause 3: balancer:// without mod_proxy_balancer#

A load-balanced setup looks like this:

<Proxy "balancer://app">
    BalancerMember "http://10.0.0.11:8000"
    BalancerMember "http://10.0.0.12:8000"
</Proxy>
ProxyPass "/" "balancer://app/"

Without mod_proxy_balancer, this config still starts. BalancerMember is defined in mod_proxy.c, not in the balancer module, so Apache accepts it. The test logged that both members were defined. Then every request failed:

[proxy:debug] AH01143: Running scheme balancer handler (attempt 0)
[proxy_http:debug] AH01113: HTTP: declining URL balancer://app/
[proxy:warn] AH01144: No protocol handler was valid for the URL / (scheme 'balancer'). ...

The balancer module is what turns balancer://app/ into one member's URL. Without it, the URL stays balancer://app/. mod_proxy_http does not know that scheme, and nothing else does either. The result was the same on 2.4.48.

The fix needs more than the one module. The mod_proxy_balancer manual says "mod_proxy, mod_proxy_balancer and at least one of load balancing scheduler algorithm modules have to be present". The test showed a third requirement. httpd 2.4.69 refused to start at each step:

1. With mod_proxy_balancer alone: AH01177: Failed to lookup provider 'shm' for 'slotmem': is mod_slotmem_shm loaded??
2. With mod_slotmem_shm added: AH02432: Cannot find LB Method: byrequests and AH01183: Cannot share balancer.
3. With mod_lbmethod_byrequests added, Apache started and the request reached the member.

LoadModule proxy_balancer_module       modules/mod_proxy_balancer.so
LoadModule slotmem_shm_module          modules/mod_slotmem_shm.so
LoadModule lbmethod_byrequests_module  modules/mod_lbmethod_byrequests.so

byrequests is the default method. If you set lbmethod=bytraffic or bybusyness, load that module instead. How members fail over and come back is in health checks and failover.

A member's module missing gives a 503, not AH01144#

The members need their own module too. Take a balancer of ajp:// members, with mod_proxy_ajp not loaded. You might expect AH01144 with scheme ajp. On 2.4.69 it was not. The request got 503, and the log said:

[proxy:error] AH00934: all workers are busy.  Unable to serve balancer://tomcats/

Nothing was busy. The balancer picked the ajp:// member, could not use it, and reported it in the only words it has. In proxy_util.c, AH00934 is logged whenever the balancer declines to hand over a worker. With mod_proxy_ajp loaded, the same request reached the connect step. So when AH00934 appears on a quiet server, check the members' schemes against apachectl -M before you look at load.

Cause 4: ws:// on httpd 2.4.46 and older#

On old releases, WebSocket URLs belonged to mod_proxy_wstunnel. A common setup sends a whole site to a WebSocket backend:

ProxyPass "/" "ws://backend:9080/"

On 2.4.46 and older, that gives AH01144 with scheme ws in two cases. The first is plain: mod_proxy_wstunnel is not loaded. The second is the one people miss. The 2.4.46 wstunnel source checks the client's Upgrade header. If it is missing or is not WebSocket, the module logs AH02900: declining URL ... (not WebSocket, Upgrade: header is missing) at debug and declines. mod_proxy_http in 2.4.46 takes only http and https, so it declines too. Every normal page load under that prefix then fails with a 500. Only the real WebSocket handshakes get through.

The mod_proxy_wstunnel manual shows the fix for that release line. Send only the WebSocket path to ws://, and put it before the general HTTP line:

ProxyPassMatch "^/(myApp/ws)$" "ws://backend.example.com:9080/$1"
ProxyPass "/" "http://backend.example.com:9080/"

httpd 2.4.47 changed this. The CHANGES file records that mod_proxy_wstunnel now leaves Upgrade requests "to mod_proxy_http", and mod_proxy_http's scheme parser now accepts ws and wss. In the 2.4.69 test, a ProxyPass to ws:// with only mod_proxy_http loaded did not log AH01144. mod_proxy took the request and went on to connect. mod_proxy_wstunnel is now marked deprecated. Its ProxyWebsocketFallbackToProxyHttp directive (2.4.48 and later, default On) hands requests to mod_proxy_http. Setting it to Off brings back the 2.4.46 behavior.

So on a current release, AH01144 with scheme ws should not come from a missing wstunnel. Check that mod_proxy_http is loaded. Headers, timeouts and the Upgrade handshake through other proxies are in WebSockets through proxies.

Not a cause: a URL with no scheme#

Many answers say that a backend URL with no scheme, or no //, produces AH01144. The source looks like it agrees. mod_proxy_http logs AH01113: HTTP: declining URL when the URL has no scheme it knows, or no // after it, or nothing after the //. But in practice, such a URL never reaches that point:

• ProxyPass checks the URL at startup. ProxyPass "/app/" "localhost:8000/" stopped httpd 2.4.69 with ProxyPass URL must be absolute!: localhost:8000/. With an IP, 10.9.9.9:8000/, it gave ProxyPass Unable to parse URL. Apache did not start, so there was no AH01144.
• RewriteRule ... [P] makes it a local path. RewriteRule "^/r/(.*)$" "localhost:8000/$1" [P] did not fail. mod_rewrite treated the target as a path on this server. Apache then proxied the request to itself, as http://<own address>:8080/localhost:8000/a, and returned a 404.
• ProxyPassMatch with an empty host fails earlier. When the captured host was empty, the request got 400 with AH01083: error parsing URL http://: Invalid host/port.

AH01113 itself is not a sign of a bad URL. mod_proxy_http logs it for every scheme that is not its own: fcgi, h2c and balancer all produced it above. Read the scheme in it, not the word "declining".

Not AH01144: SetHandler with mod_proxy_fcgi missing#

PHP-FPM is often wired with SetHandler instead of ProxyPass. The mod_proxy manual's own example is:

<FilesMatch "\.php$">
    SetHandler "proxy:unix:/path/to/app.sock|fcgi://localhost"
</FilesMatch>

With mod_proxy_fcgi not loaded, you might expect AH01144 with scheme fcgi. You do not get it. In the 2.4.69 test, with SetHandler "proxy:fcgi://127.0.0.1:9000", Apache logged nothing at all. It returned 200 OK with the raw PHP file as the body: <?php echo 1;.

The source shows why. For a SetHandler "proxy:...", mod_proxy.c first asks a module to check the URL. With no module for fcgi, that check fails. mod_proxy then puts the request back as it was and steps aside. Apache serves the file as a plain static file. On a real site, that means visitors can download your PHP source, config values and all. If PHP pages show up as code, check apachectl -M for proxy_fcgi_module first.

Worked case: PHP-FPM on a fresh Debian server#

Take a fresh Debian server with Apache 2.4 and PHP-FPM listening on 127.0.0.1:9000. Suppose the admin ran a2enmod proxy and added this line to the site:

ProxyPassMatch "^/(.*\.php)$" "fcgi://127.0.0.1:9000/var/www/html/$1"

Apache restarts cleanly. Then every .php page returns 500 Internal Server Error. Walk it through with the rules above.

1. The error log at the default level shows AH01144: No protocol handler was valid for the URL /index.php (scheme 'fcgi'). The path is the visitor's request. The scheme is fcgi.
2. The table maps fcgi to mod_proxy_fcgi. apachectl -M | grep proxy would list only proxy_module. a2enmod proxy enabled the core, not the FastCGI part.
3. Run a2enmod proxy_fcgi and restart. The scheme now has a taker, so AH01144 stops.
4. If a PHP page still fails, it is no longer this error. A 503 means Apache could not reach PHP-FPM on port 9000. A PHP error page means the request arrived. Either way, AH01144 is gone.

Now suppose the same admin had used the SetHandler form from the mod_proxy manual instead. Step 1 would never happen. There would be no 500 and no log line. The pages would come back as source code. The fix is the same a2enmod proxy_fcgi, but nothing in the log would have pointed to it.

Where this answer stops applying#

This page covers httpd 2.4, tested on 2.4.69 and 2.4.48 in the official Docker images with hand-written configs. Line numbers in the log move between releases, so search by AH number. The ws:// behavior of 2.4.46 and older comes from that release's source and the CHANGES file and was not run. Distribution packages load different modules by default and may patch httpd, so check apachectl -M on your own server rather than trusting a default. mod_proxy_connect (forward proxy CONNECT), mod_proxy_ftp, mod_proxy_scgi and mod_proxy_uwsgi were not tested. Nor were ProxyRemote chains, where a request can go to another proxy first. Once AH01144 is gone, the request reaches the backend, and its failures have other names: a failed connect is a 503 with AH01114, a reply that never comes is a 502 with AH01102. How those codes differ across proxies is in 502 vs 503 vs 504.

Frequently asked questions#

What does No protocol handler was valid for the URL mean?#

Apache's mod_proxy offered the backend URL to every loaded proxy module, and none accepted it. Apache returns 500 and logs AH01144 at warn level. The scheme at the end of the line names the kind of backend, and usually the missing module.

Why does AH01144 show my path and not the backend URL?#

The message prints the client's request path (r->uri) and the backend's scheme. The backend URL is in the debug line AH01113: HTTP: declining URL ..., which mod_proxy_http logs when it is loaded and LogLevel proxy_http:debug is set.

Which LoadModule line fixes AH01144?#

The one for the scheme: proxy_http_module for http, proxy_fcgi_module for fcgi, proxy_http2_module for h2 or h2c, proxy_ajp_module for ajp. For https, load ssl_module as well. For balancer, load proxy_balancer_module, slotmem_shm_module and an lbmethod module.

Why do I get AH01144 with scheme https when mod_proxy_http is loaded?#

mod_ssl is not loaded. mod_proxy_http declines HTTPS URLs when no module can do TLS on the outgoing connection, and it says so only at debug level with AH01112 ... (mod_ssl not configured?). Load mod_ssl, then add SSLProxyEngine on.

Why does my balancer:// config give No protocol handler was valid?#

mod_proxy_balancer is not loaded, so the balancer:// URL is never turned into a member's URL. BalancerMember is a mod_proxy directive, so Apache still starts. Load mod_proxy_balancer, mod_slotmem_shm and mod_lbmethod_byrequests.

Do I still need mod_proxy_wstunnel for ws:// URLs?#

Not on httpd 2.4.47 or later. mod_proxy_http handles ws:// and wss:// and the WebSocket upgrade itself, and the wstunnel module is deprecated. On 2.4.46 and older you need it, and a ws:// URL fails with AH01144 for any request without an Upgrade: WebSocket header.

Can a missing scheme in ProxyPass cause AH01144?#

No. ProxyPass checks the URL when Apache starts. A URL like localhost:8000/ stops startup with ProxyPass URL must be absolute!. A RewriteRule [P] target with no scheme is treated as a local path instead.