Docker Compose "network declared as external, but could not be found"

A network marked external: true must already exist - Compose will not create it. It looked for that network by name and did not find one, so it refuses to start the services.

What this error means

A docker compose up fails immediately with network "X" declared as external, but could not be found. Compose creates non-external networks automatically, but an external one is your responsibility to provision first.

docker compose output

network shared-net declared as external, but could not be found
# compose.yml has:
#   networks:
#     shared-net:
#       external: true

Common causes

The external network was never created

Marking a network external: true tells Compose to attach to an existing one. If nothing created shared-net first, there is nothing to attach to.

Name mismatch with the actual network

The external network exists under a different name (or a project-prefixed name) than the one declared, so the lookup fails.

How to fix it

Create the external network before up

Provision the network first, then bring the stack up.

Terminal

docker network create shared-net
docker compose up -d

Or let Compose manage the network

If the network does not need to be shared across projects, drop external: true so Compose creates it.

docker-compose.yml

networks:
  shared-net:        # no "external: true" -> compose creates it

How to prevent it

Create external networks as a setup step before compose up in CI.
Match the declared name to the real network name exactly.
Only mark networks external when they are genuinely shared across projects.