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

By Kaveh Alemi·Latchkey

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

Diagnose it: read the resolved config, not the file you wrote

Compose merges override files, interpolates variables, and applies defaults before it does anything. Most Compose failures in CI are visible in the resolved configuration and invisible in the source file, because the value you are debugging came from an unset variable that quietly became an empty string.

Terminal

# the fully merged, interpolated configuration Compose will actually run
docker compose config

# fail loudly on unset variables instead of silently interpolating empty
docker compose --env-file .env config --quiet || echo "invalid"

# which override files were picked up
docker compose config --services

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

Bind mounts behave differently on a runner

A relative bind source is resolved against the compose file location, not the working directory of the shell that invoked it.
The host path must exist before up. Compose creates missing directories for named volumes but not for bind mounts, and the failure surfaces as a mount error rather than a missing-path error.
On a CI runner the workspace path differs from your machine, so any absolute host path in a compose file is a portability bug waiting for its first CI run.
Prefer named volumes for anything that does not genuinely need to be read from the host. They remove the whole class of problem.

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.

Frequently asked questions

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

There are 2 common causes: the external network was never created and name mismatch with the actual network. Marking a network external: true tells Compose to attach to an existing one.

How do I fix Docker Compose "network declared as external, but could not be found"?

There are 2 fixes depending on which cause you have: create the external network before up and or let compose manage the network. Work through them in order, since the first is the most common.

What does Docker Compose "network declared as external, but could not be found" actually mean?

A docker compose up fails immediately with network "X" declared as external, but could not be found.

How do I stop Docker Compose "network declared as external, but could not be found" happening again?

Create external networks as a setup step before compose up in CI. The prevention section lists 3 changes that keep it from recurring.