This error occurs when your Docker Compose file references a network marked as external, but Docker cannot find a pre-existing network with that name. The fix is to either create the network manually or remove the external flag.
The "Network declared as external but could not be found" error occurs when Docker Compose tries to connect services to a network that is marked with `external: true`, but no such network exists on the Docker host. When you declare a network as `external` in your docker-compose.yml, you're telling Compose: "This network already exists - don't create it, just connect to it." However, if the network doesn't actually exist, Compose cannot proceed and throws this error. This is a common source of confusion because Compose normally creates networks automatically. The `external: true` flag changes this behavior, making you responsible for creating the network beforehand. This is particularly useful when: - Multiple Compose projects need to share the same network - You need a network with specific configuration that Compose doesn't support - You want to integrate Compose-managed containers with manually created ones
First, check what networks currently exist on your Docker host:
docker network lsLook for the network name mentioned in the error. If it's not listed, you'll need to create it. Pay attention to the exact spelling and case - network names are case-sensitive.
You can also filter for a specific name:
docker network ls --filter name=mynetworkCreate the network that your docker-compose.yml expects:
docker network create mynetworkFor a bridge network (the default), this is all you need. If you need specific options:
# Create with a specific subnet
docker network create --subnet=172.28.0.0/16 mynetwork
# Create with a specific driver
docker network create --driver bridge mynetworkAfter creating the network, run docker-compose up again.
Check your docker-compose.yml to ensure the network name matches exactly:
networks:
mynetwork:
external: trueIf you're using the name property, verify it matches the created network:
networks:
app_network:
name: mynetwork
external: trueIn this case, the internal reference is app_network, but Docker looks for a network named mynetwork.
Use docker compose config to see the resolved configuration including any variable substitutions:
docker compose configIf you don't actually need to share this network with other projects or manually-created containers, simply remove external: true:
Before:
networks:
mynetwork:
external: trueAfter:
networks:
mynetwork:
driver: bridgeOr remove the networks section entirely - Compose will create a default network automatically:
services:
web:
image: nginx
db:
image: postgres
# No networks section needed - Compose creates a default networkSince Docker Compose version 3.5+, you can use the name property to control the exact network name without the project prefix:
networks:
shared:
name: shared_network
driver: bridgeThis creates a network called exactly shared_network (not projectname_shared_network). When you need to share it across projects, other Compose files can reference it as external:
networks:
shared:
name: shared_network
external: trueThis approach avoids needing to manually create networks in most cases - the first Compose project to start will create it.
When multiple Compose projects need to communicate, create a shared external network:
# Create the shared network once
docker network create shared_netThen in each docker-compose.yml:
services:
app:
image: myapp
networks:
- shared_net
- default # Also keep the default network for internal services
networks:
shared_net:
external: trueServices on the shared network can reach each other using their service names as hostnames.
Automating network creation in CI/CD: In CI/CD pipelines, create the network before running compose:
docker network inspect mynetwork >/dev/null 2>&1 || docker network create mynetwork
docker compose up -dUsing environment variables for network names: If you use variables in network names, ensure they're set:
networks:
app_net:
name: ${NETWORK_NAME:-default_network}
external: trueCheck the resolved name with docker compose config.
Network driver considerations: External networks can use any driver. If you're using overlay networks for Swarm or custom network plugins, ensure the driver is available:
docker network create --driver overlay --attachable mynetworkThe --attachable flag allows standalone containers (not just Swarm services) to connect.
Docker contexts and remote hosts: If you're using Docker contexts to manage multiple Docker hosts, the network must exist on the host you're currently targeting:
# Check current context
docker context show
# List networks on current context
docker network ls
# Switch context if needed
docker context use productionCompose V2 vs V1: Docker Compose V2 (docker compose) handles networks slightly differently than V1 (docker-compose). V2 is more strict about external network existence checks. If upgrading from V1, you may need to create networks that V1 was silently creating or ignoring.
Cleanup and troubleshooting: If you suspect stale network state:
# Remove unused networks
docker network prune
# Force remove a specific network (disconnect all containers first)
docker network rm mynetwork
# Recreate fresh
docker network create mynetworkimage operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub