Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Apache in a Docker container logs AH01114 when it proxies to a backend

ErrorAH01114: HTTP: failed to make connection to backend: localhost

Short 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.

  • Applies to Apache httpd 2.4, Docker Engine 28, Docker Compose v2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 api
  2. 2Match what you see, then jump to its fix

    1. 1AH01114 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. 2The 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. 3getent hosts api prints nothing inside the Apache container, although the api container is runningThe two containers are not on the same networkFix
    4. 4AH01114 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. 5AH01114 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

What does the error look like?

  • AH01114: HTTP: failed to make connection to backend: localhost
  • AH01114: 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.conf

2Fix

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:latest

3Verify

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

Did this fix it?

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 api

2Fix

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

Did this fix it?

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 api

Confirmed by docs.docker.com

Did this fix it?

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.internal

2Fix

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-apache

3Verify

Call the proxied path from the host.

curl -I http://localhost:8080/api/

Confirmed by docs.docker.com

Did this fix it?

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.conf

2Fix

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 graceful

3Verify

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

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.