Maaz Zindani

Loading the index…

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

Reaching a service on the host's localhost from inside a Docker container

Errorconnect ECONNREFUSED 127.0.0.1:5432

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

  • Applies to Docker Engine 28, Docker Desktop 4.34+, Docker Compose v2, PostgreSQL 16, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1connect 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. 2getaddrinfo ENOTFOUND host.docker.internal, and getent prints nothingOn Linux, host.docker.internal does not exist until you add itFix
    3. 3The name resolves to 172.17.0.1, but the connection is refused at onceThe host service listens only on 127.0.0.1Fix
    4. 4The connection hangs and ends in ETIMEDOUT instead of being refusedA host firewall drops packets from containersFix
    5. 5localhost:5433 works from your machine, but the app container can't reach the database containerThe service is another container in the same Compose projectFix

What does the error look like?

  • connect ECONNREFUSED 127.0.0.1:5432
  • getaddrinfo ENOTFOUND host.docker.internal
  • could not translate host name "host.docker.internal" to address: Name or service not known
  • connect 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/app

3Verify

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 app
Did this fix it?

Cause 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/hosts

2Fix

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.internal
Did this fix it?

Cause 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 5432

2Fix

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

3Verify

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 5432
Did this fix it?

Cause 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 verbose

2Fix

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 tcp

3Verify

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 app
Did this fix it?

Cause 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 ps

2Fix

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/app

3Verify

The service name resolves inside the app container.

docker compose exec app getent hosts db
Did this fix it?

How 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

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

Next step

Want this handled for good?

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