Apache in a Docker container logs AH01114 when it proxies to a backend
AH01114: HTTP: failed to make connection to backend: localhostShort answer
Apache's proxy worker could not open a connection to the address in ProxyPass. In Docker the usual reasons are that localhost means the Apache container itself, the backend port is the published host port instead of the container port, or the two containers share no network. Use the service name and the container port.
Fix it fast
1Find out which cause you have
Look at what Apache is told to proxy to, then ask the Apache container whether that name resolves from inside it.
grep -n -E "ProxyPass|ProxyPassReverse" httpd.conf docker compose exec web getent hosts api2Match what you see, then jump to its fix
- 1
AH01114 names localhost or 127.0.0.1, the backend runs as its own service, and the same URL works from the hostProxyPass says localhost, but the backend is another containerFix - 2
The service name resolves, but the connection is refused; the compose file maps a different number on the left, such as 3001:3000ProxyPass uses the host port, not the container portFix - 3
getent hosts api prints nothing inside the Apache container, although the api container is runningThe two containers are not on the same networkFix - 4
AH01114 names localhost, and the app was started with a normal command on your machine, not as a containerThe backend runs on the Docker host, outside any containerFix - 5
AH01114 appears right after the backend was recreated or started late, and goes away after a minute or after Apache is reloadedApache kept an old address, or still treats the backend as failed, after a restartFix
- 1
What does the error look like?
AH01114: HTTP: failed to make connection to backend: localhostAH01114: HTTP: failed to make connection to backend: api
Cause 1 of 5
ProxyPass says localhost, but the backend is another container
1Check
Inside the Apache container, localhost is the Apache container, so nothing listens there. Containers of one Compose project reach each other by service name, through the project network that Compose creates.
grep -n -E 'ProxyPass' httpd.conf2Fix
Replace localhost with the Compose service name. If the first argument ends with a slash, the second one has to end with one too.
# httpd.conf
ProxyPass "/api/" "http://api:3000/"
ProxyPassReverse "/api/" "http://api:3000/"
# compose.yaml
services:
web:
image: httpd:2.4
ports:
- "8080:80"
api:
image: my-api:latest3Verify
Restart the Apache container so it reads the file, then request the proxied path from the host.
docker compose restart web
curl -I http://localhost:8080/api/Confirmed by docs.docker.com
Cause 2 of 5
ProxyPass uses the host port, not the container port
1Check
Between containers, the port to use is the CONTAINER_PORT on the right of the mapping. The number on the left exists only for access from outside the Compose network.
docker compose ps api2Fix
Point ProxyPass at the container port. You can then drop the published port if only Apache needs to reach the backend.
# compose.yaml: api publishes 3001 on the host, listens on 3000 inside
# ports: ["3001:3000"]
# httpd.conf
ProxyPass "/api/" "http://api:3000/"
ProxyPassReverse "/api/" "http://api:3000/"3Verify
Reload Apache gracefully, then call the proxied path.
docker compose exec web apachectl -k graceful
curl -I http://localhost:8080/api/Confirmed by docs.docker.com
Cause 3 of 5
The two containers are not on the same network
1Check
A user-defined bridge network resolves container names for the containers attached to it. Containers on different bridge networks are isolated, and a container started with plain docker run sits on the default bridge, where names do not resolve.
docker inspect -f '{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{end}}' $(docker compose ps -q web)
docker inspect -f '{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{end}}' $(docker compose ps -q api)2Fix
Put both services on one network in the compose file, or attach the running container to the network with docker network connect.
services:
web:
image: httpd:2.4
networks: [shared]
api:
image: my-api:latest
networks: [shared]
networks:
shared:3Verify
The name now resolves from the Apache container.
docker compose up -d
docker compose exec web getent hosts apiConfirmed by docs.docker.com
Cause 4 of 5
The backend runs on the Docker host, outside any container
1Check
Docker Desktop defines the name host.docker.internal for the host. On Linux Engine the docs show it mapped by hand with --add-host and the special host-gateway value.
docker compose exec web getent hosts host.docker.internal2Fix
Proxy to host.docker.internal. On Linux Engine, map the name in the container's run options first.
# httpd.conf
ProxyPass "/api/" "http://host.docker.internal:3000/"
ProxyPassReverse "/api/" "http://host.docker.internal:3000/"
# Linux Engine, plain docker run
docker run --add-host host.docker.internal=host-gateway -p 8080:80 my-apache3Verify
Call the proxied path from the host.
curl -I http://localhost:8080/api/Confirmed by docs.docker.com
Cause 5 of 5
Apache kept an old address, or still treats the backend as failed, after a restart
1Check
A recreated container joins the network under the same name but a different IP address. With connection reuse on, which is the default, Apache resolves each backend name once per child process. After a failed connection a worker also rests in an error state for 60 seconds by default before Apache retries it.
grep -n -E 'retry|disablereuse' httpd.conf2Fix
Let Apache look the name up again and retry at once, and reload Apache gracefully after backend redeploys.
# httpd.conf
ProxyPass "/api/" "http://api:3000/" retry=0 disablereuse=On
# reload without cutting requests in progress
docker compose exec web apachectl -k graceful3Verify
Recreate the backend and call the proxied path straight away.
docker compose up -d --force-recreate api
curl -I http://localhost:8080/api/Confirmed by httpd.apache.org
How do I stop it coming back?
- Never write localhost in a ProxyPass URL when the target is another container: use the service name and the container port.
- Keep Apache and its backends in one Compose project, or on one named network.
- Add a healthcheck to the backend and make Apache wait for it with depends_on, so the proxy never starts against a service that is not ready.
- After a backend redeploy, reload Apache gracefully instead of restarting it, so requests in progress finish.
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
Servers
Reaching a service on the host's localhost from inside a Docker container
getaddrinfo ENOTFOUND host.docker.internal
Inside a container, localhost is the container itself, not your machine.
5 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fixServers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fix