Debug a cross-network connection refused
Medium

Problem

Your app's web container starts up but can't reach db. The error in the web logs is explicit — connection refused on db:5432. The database itself is healthy and running; the cache (redis) that lives next to the database is fine. So this isn't a dead postgres. It's a wiring problem.

Your job: find the network misconfiguration and connect web to db so the connect retry loop succeeds.

Initial setup

Three containers are up:

  • web — your app, attached to the default bridge network (172.17.0.0/16)
  • db — postgres, attached to a user-defined backend network (172.20.0.0/16)
  • cache — redis, attached to backend
Networks on the host: bridge, backend, host.

Example interaction

$ docker logs web | tail -5
Attempting to connect to db:5432...
Error: could not connect to server: Connection refused
        Is the server running on host "db" (172.17.0.1) and accepting
        TCP/IP connections on port 5432?
Retrying in 5s...

$ docker network ls
NETWORK ID     NAME       DRIVER    SCOPE
a1b2c3d4e5f6   bridge     bridge    local
b2c3d4e5f6a1   backend    bridge    local
c3d4e5f6a1b2   host       host      local

Notice the resolver returned 172.17.0.1 for db — that's the bridge network's gateway, not an actual container. Docker's embedded DNS only resolves container names _across containers on the same user-defined network_. Two containers on bridge vs backend can't find each other by name.

Acceptance

You've solved it when:

  • You've confirmed web and db are on different networks (docker network inspect <name> is the authoritative source).
  • You've attached web to the backend network (or detached db/cache onto bridge, whichever you prefer — the fix is symmetric).
  • After the fix, web resolves db to its backend-network IP and the connect error stops.

Constraints

  • Tools: docker CLI only.
  • Time limit: 15 minutes.
  • Don't destroy & recreate db — it has data. The fix must preserve the running db container.

Follow-up

  1. Why does Docker's default bridge network behave differently from a user-defined bridge network when it comes to container-name DNS resolution?
  2. A container can be on multiple networks at once. Is there a scenario where putting web on both bridge and backend is better than moving it off bridge entirely?
Live session
Code
SavedNo commands yet