7.3.2.3 Missing Network Membership

Missing network membership occurs when one container in a multi-container application was created without joining the same network as the other containers it needs to communicate with, a common oversight especially as an application grows to include additional components over time.

How This Oversight Typically Happens

A new container added to an existing multi-container setup is sometimes created without explicitly specifying the same network the rest of the application already uses, defaulting instead to the default bridge network.

docker network create app-network
docker run -d --name api --network app-network myapi:1.0
docker run -d --name db --network app-network postgres:16
docker run -d --name worker workerimage:1.0

The newly added worker container, created without an explicit --network flag, ends up on the default bridge rather than app-network, leaving it unable to resolve or reach api or db at all.

Confirming This Is the Actual Cause

Checking which network each relevant container is actually attached to reveals whether one of them is missing from the expected shared network.

docker network inspect app-network --format '{{json .Containers}}'

If worker doesn't appear in this output, it confirms the container is missing from the network it actually needs to be part of.

The Fix: Connecting the Missing Container to the Network

A running container can be connected to an additional network without needing to be recreated.

docker network connect app-network worker

Preventing This Oversight Going Forward

Establishing a consistent practice — always explicitly specifying the application's intended network when creating any new container belonging to it — helps avoid this specific oversight recurring as an application grows.

docker run -d --name new-component --network app-network new-component-image:1.0

Why Recognizing Missing Network Membership Matters

This specific, easily made oversight becomes more likely as a multi-container application grows over time and new components are added — explicitly checking network membership for every component is a straightforward way to catch and resolve this particular cause of communication failures.