This error occurs when Docker Compose tries to connect a service to an external network that doesn't exist. External networks must be created manually using 'docker network create' before running docker-compose, or you can remove the external flag to let Compose create the network automatically.
When you declare a network as `external: true` in your `docker-compose.yml` file, you're telling Docker Compose that this network already exists and was created outside of the current Compose project. Docker Compose will not attempt to create it - instead, it expects to find an existing network with that name. The "declared as external, but could not be found" error means Docker Compose queried the Docker daemon for a network with the specified name and didn't find one. This commonly happens when: - You're setting up a project for the first time and forgot to create the network - The network was deleted or never existed - There's a mismatch between the network name in your Compose file and the actual network name - You're running in a Docker Swarm environment where overlay networks need special handling External networks are useful when you want multiple Compose projects to share a common network, or when you need to connect containers managed by Compose to containers managed directly by Docker.
The most direct fix is to create the network that Docker Compose is looking for:
# Create a basic bridge network
docker network create mynetwork
# Verify it was created
docker network ls | grep mynetworkReplace mynetwork with the actual network name from your error message.
For Swarm mode overlay networks:
docker network create -d overlay --attachable mynetworkCheck your docker-compose.yml to see how the network is defined:
networks:
mynetwork:
external: trueOr with an explicit name:
networks:
mynetwork:
name: my-actual-network-name
external: trueList existing networks to find the correct name:
docker network lsIf there's a name mismatch, either:
1. Update the Compose file to use the correct network name
2. Create a new network with the name Compose expects
If you don't actually need to share this network with other projects or manually-created containers, remove the external: true flag:
Before (external network):
networks:
mynetwork:
external: trueAfter (Compose-managed network):
networks:
mynetwork:
driver: bridgeOr simply don't define the network at all - Docker Compose creates a default network automatically:
services:
web:
image: nginx
api:
image: myapi
# No networks section needed - services can communicate by service nameDocker Compose prefixes auto-created networks with the project name. If you're referencing a network created by another Compose project, include the full name:
# List networks to see full names
docker network ls
# Output might show:
# myproject_default
# otherapp_sharedUpdate your Compose file to use the full network name:
networks:
shared:
name: otherapp_shared
external: trueThe name field specifies the actual Docker network name, while the key (shared) is just the alias within your Compose file.
If the network is created by another docker-compose project, start that project first:
# Start the project that creates the network
cd /path/to/other-project
docker-compose up -d
# Verify the network exists
docker network ls
# Now start your project
cd /path/to/your-project
docker-compose up -dFor a more robust solution, create a shared network in a startup script rather than depending on another Compose project.
If you're using Docker Swarm, overlay networks require special handling:
# Initialize swarm if not already done
docker swarm init
# Create an attachable overlay network
docker network create -d overlay --attachable mynetwork
# Verify it's an overlay network
docker network inspect mynetwork | grep DriverIn your Compose file:
networks:
mynetwork:
external: true
# driver: overlay is inferred from the existing networkNote: On Swarm worker nodes, overlay networks may not be immediately visible until a service uses them. The network is created on the manager but only materializes on workers when needed.
Multiple Compose files sharing a network: When multiple projects need to communicate, create a dedicated shared network:
# Create once during system setup
docker network create shared-servicesThen in each Compose file:
services:
myservice:
networks:
- default # Internal project network
- shared # Cross-project communication
networks:
shared:
name: shared-services
external: trueCI/CD considerations: In CI pipelines, networks don't persist between runs. Either:
1. Remove external: true and let Compose manage the network
2. Add a setup step to create the network before docker-compose up
3. Use docker-compose up with the --force-recreate flag
Docker Compose version differences: In older Compose file versions (2.x), external networks were defined differently:
# Old format (deprecated)
networks:
outside:
external:
name: actual-name-of-network
# New format (Compose file 3.5+)
networks:
outside:
name: actual-name-of-network
external: trueDebugging network issues:
# List all networks with details
docker network ls
# Inspect a specific network
docker network inspect mynetwork
# See which containers are connected to a network
docker network inspect mynetwork -f '{{range .Containers}}{{.Name}} {{end}}'dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec