Reaching a service on the host's localhost from inside a Docker container
connect ECONNREFUSED 127.0.0.1:5432Short answer
Inside a container, localhost is the container itself, not your machine. Point the app at host.docker.internal instead. Docker Desktop defines that name for you; on Linux you add it with host-gateway, and the host service must listen on the Docker bridge address, not only on 127.0.0.1. If the target runs in the same Compose project, use its service name.
Fix it fast
1Find out which cause you have
Ask the app container what host.docker.internal resolves to, then try the database from a throwaway container. No address means the name is missing. "Connection refused" points at the host service's bind address, "timeout expired" points at a firewall, and a password or pg_hba.conf error means the network path already works.
docker exec my-app getent hosts host.docker.internal docker run --rm --add-host host.docker.internal=host-gateway -e PGCONNECT_TIMEOUT=5 postgres:16 psql -w -h host.docker.internal -U app -c 'select 1'2Match what you see, then jump to its fix
- 1
connect ECONNREFUSED 127.0.0.1:5432 (or ::1) inside the container, while the same settings work when the app runs directly on the hostThe app's settings say localhost, which is the container itselfFix - 2
getaddrinfo ENOTFOUND host.docker.internal, and getent prints nothingOn Linux, host.docker.internal does not exist until you add itFix - 3
The name resolves to 172.17.0.1, but the connection is refused at onceThe host service listens only on 127.0.0.1Fix - 4
The connection hangs and ends in ETIMEDOUT instead of being refusedA host firewall drops packets from containersFix - 5
localhost:5433 works from your machine, but the app container can't reach the database containerThe service is another container in the same Compose projectFix
- 1
What does the error look like?
connect ECONNREFUSED 127.0.0.1:5432getaddrinfo ENOTFOUND host.docker.internalcould not translate host name "host.docker.internal" to address: Name or service not knownconnect ETIMEDOUT 172.17.0.1:5432
Cause 1 of 5
The app's settings say localhost, which is the container itself
1Check
Print the connection settings the container actually received. Every container has its own network namespace, so 127.0.0.1 in there is the container's own loopback, and nothing listens on the database port in it.
docker exec my-app env | grep -iE 'host|url|port'2Fix
Replace localhost with host.docker.internal, and pass it in through the environment rather than a config file baked into the image, so the same image runs on a laptop and on a server.
# compose.yaml
services:
app:
image: my-app
environment:
DATABASE_URL: postgres://app:${DB_PASSWORD}@host.docker.internal:5432/app3Verify
Recreate the container and read its first log lines for a successful database connection.
docker compose up -d --force-recreate app
docker compose logs --tail 30 appCause 2 of 5
On Linux, host.docker.internal does not exist until you add it
1Check
Docker Desktop on macOS and Windows resolves host.docker.internal on its own. Docker Engine on Linux does not: the name is only there if you map it. Look for it in the container's hosts file.
docker exec my-app cat /etc/hosts2Fix
Map the name to the special value host-gateway. Docker swaps in the host's address on the default bridge (usually 172.17.0.1). Compose's extra_hosts accepts the same value as docker run's --add-host.
# docker run
docker run -d --add-host host.docker.internal=host-gateway my-app
# compose.yaml
services:
app:
extra_hosts:
- "host.docker.internal:host-gateway"3Verify
The container now has a hosts entry for the name, pointing at the bridge address.
docker compose exec app getent hosts host.docker.internalCause 3 of 5
The host service listens only on 127.0.0.1
1Check
On Linux the request reaches the host on the bridge address, not on its loopback, so a database or cache bound to 127.0.0.1 never sees it. Check which address the port is bound to.
sudo ss -ltnp | grep 54322Fix
Option A: let the service listen on the bridge address too, and allow Docker's subnets in its own access rules. The bridge address only exists once Docker is running, so restart the database after Docker starts. Option B, on Linux: run the container with network_mode host; 127.0.0.1 inside it is then the host's loopback, but published ports are ignored and the container leaves the Compose network. Docker Desktop supports host networking from version 4.34 once you turn on Enable host networking in Settings.
# Option A, PostgreSQL: /etc/postgresql/16/main/postgresql.conf
listen_addresses = 'localhost,172.17.0.1'
# /etc/postgresql/16/main/pg_hba.conf (Docker's default networks sit inside 172.16.0.0/12)
host all all 172.16.0.0/12 scram-sha-256
sudo systemctl restart postgresql
# Option B, compose.yaml on Linux
services:
app:
network_mode: host # the app now uses 127.0.0.1:54323Verify
Test from a throwaway container on the app's own network, so the source address matches the real one.
docker run --rm --network myproject_default --add-host host.docker.internal=host-gateway postgres:16 pg_isready -h host.docker.internal -p 5432Cause 4 of 5
A host firewall drops packets from containers
1Check
A timeout means packets are being dropped, not rejected. With ufw's default deny-incoming policy, a connection from a container to the host's own address is filtered like any other inbound connection. Find the subnet of the app's network and look for a rule that lets it in.
docker network inspect myproject_default --format '{{(index .IPAM.Config 0).Subnet}}'
sudo ufw status verbose2Fix
Allow that one subnet to that one port. Turning the firewall off fixes the symptom and opens the database to everyone else.
sudo ufw allow from 172.18.0.0/16 to any port 5432 proto tcp3Verify
Confirm the rule is in place, restart the app and read its logs.
sudo ufw status numbered | grep 5432
docker compose restart app && docker compose logs --tail 20 appCause 5 of 5
The service is another container in the same Compose project
1Check
Compose puts all services of a project on one network with its own DNS, so containers find each other by service name on the port used inside the container. The ports mapping only matters for traffic coming from outside Docker.
docker compose config --services
docker compose ps2Fix
Use the service name and the container port. Going out through host.docker.internal and the published port also works, but it adds a hop and breaks as soon as someone changes the mapping.
services:
db:
image: postgres:16
ports:
- "5433:5432" # only for tools on your machine
app:
environment:
DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app3Verify
The service name resolves inside the app container.
docker compose exec app getent hosts dbHow do I stop it coming back?
- Pass hosts and ports in through environment variables; never bake localhost into an image.
- Put the host-gateway mapping in every Compose file that needs the host, so one file works on Linux servers and on Docker Desktop.
- Run databases that only containers use inside Compose and reach them by service name; publish ports only for the tools that need them.
- Open host services to Docker's subnets only, never to every address without a firewall rule in front.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. 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
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 fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fixServers
A dev container port does not open in the browser when Docker runs on a remote host
If your application only accepts calls from localhost, it will reject connections from published ports
Three things usually break it: the app listens only on localhost inside the container, so published ports are rejected; you open the container port instead of the mapped localhost port VS Code shows; or you changed appPort or a Compose ports list and did not rebuild.
3 causes, each with a fix