Docker Compose "network not found" in CI

By Kaveh Alemi·Latchkey

Compose referenced a network that does not exist. Either an external network was never created, or a stale network ID lingers from a previous run that was partially torn down.

What this error means

A docker compose up fails with network <name> not found or network <name> declared as external, but could not be found. Recreating the network or removing the external flag fixes it.

network shared-net declared as external, but could not be found
Error response from daemon: network <id> not found

Common causes

External network not pre-created

A network marked external: true must already exist; CI never created it.

Stale network reference

A leftover network ID from an incomplete prior run no longer resolves.

How to fix it

Create the external network first

1. Create the network before compose up, or let compose manage it (drop external).

docker network create shared-net
docker compose up -d

Clean up stale state

1. Prune dangling networks between runs so old IDs do not linger.

docker network prune --force

How to prevent it

• Create external networks as an explicit setup step (or let compose own them), and prune networks between runs on shared runners. This is deterministic, not transient.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation