Connection refused between containers

Before you start

• A terminal where you can run docker commands against the host running both containers (root-equivalent on Linux).
• The names of both containers or Compose services, and the network you expect them to share, from docker network ls and docker inspect.
• A way to run tools next to the app. Slim images often lack sh, getent, nslookup, ss or netstat; if so, start a throwaway container on the same network, as Docker's docs do with docker run --rm -it --network my-net busybox.
• The connection string the application uses (host, port, user) with the password removed.
• The port the target listens on inside its container, from its image documentation or docker port <container>.

Work out which cause you have

A few questions to narrow the list. Every answer ends in a command that confirms or rules the cause out — this cannot see your cluster, so nothing here is a certainty until you have checked.

Check it with a tool

• EXPOSE vs published ports — the same three layers→
• Check the Dockerfile→
• From docker run to compose.yaml, with a shared network→

Or diagnose it manually

In this order. The first command usually contains the whole answer.

1. Step 1

   docker exec <app> sh -c 'getent hosts db || nslookup db'

   Separates resolution from connection immediately, which is the fork in this whole investigation.

   Look for An address means DNS works, so the problem is further along. No answer means a network problem.

2. Step 2

   docker exec <db> sh -c 'ss -tlnp 2>/dev/null || netstat -tlnp'

   If the name resolves, the next question is whether anything is actually listening on a reachable address.

   Look for 0.0.0.0:<port> rather than 127.0.0.1:<port>.

3. Step 3

   docker inspect <app> --format '{{json .NetworkSettings.Networks}}'

   Confirms which networks the containers share, which determines whether names can resolve at all.

   Look for A user-defined network appearing in both containers' output.

Every cause, and how to fix it

Ordered by how often each one turns out to be the answer.

docker exec <app> printenv | grep -iE 'host|url|_addr'

# compose
services:
  app:
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/app
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: app

docker inspect <app> --format '{{json .NetworkSettings.Networks}}' && docker inspect <db> --format '{{json .NetworkSettings.Networks}}'

docker network create appnet
docker run -d --name db --network appnet -e POSTGRES_PASSWORD=<password> postgres:16
docker run -d --name app --network appnet myapp

docker exec <db> sh -c 'ss -tlnp 2>/dev/null || netstat -tlnp'

docker compose logs db | head -30

services:
  db:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 10
  app:
    depends_on:
      db:
        condition: service_healthy

docker port <db>

docker network inspect <network> --format '{{range .Containers}}{{.Name}} {{end}}'

How to know it is actually fixed

• ✓docker exec <app> sh -c 'getent hosts db' returns an address.
• ✓The application connects on start-up without retrying, and its logs show no connection errors.
• ✓The connection survives restarting the dependency, which confirms the client retries rather than depending on start order.

Stopping it happening again

• Use service names and container ports in configuration, and treat localhost in a container's config as a bug on sight.
• Give dependencies healthchecks and depend on health rather than on creation.
• Make clients retry with backoff. Start-order configuration only helps at start-up, and dependencies fail at other times too.

Security considerations

• Do not fix this by publishing the database port with -p 5432:5432. Containers on a shared network do not need it, and a port published without an address listens on all host interfaces and, per Docker's documentation, bypasses ufw rules.
• Give each stack its own user-defined network. Docker's documentation warns that every container started without --network joins the default bridge, where unrelated containers can talk to each other. For back-end services that need no outside access, docker network create --internal restricts external access to the network.
• Making a server listen on 0.0.0.0 inside its container does not publish it. In the bridge driver's default nat gateway mode, other machines and containers on other networks reach it only through a port you publish. The nat-unprotected mode, kept for legacy behaviour, also lets direct routing reach unpublished ports, so check a network's gateway mode before relying on this.
• The confirm step docker exec <app> printenv prints whole connection strings, passwords included. Redact them before sharing, and remember that anyone with access to the Docker daemon can read the same values with docker inspect.
• Do not make localhost work by switching to network_mode: host. Docker's Compose documentation warns that such a container can access all host ports and observe all network traffic on the host.