Fix Docker Compose error: external network not found

Overview

You run docker compose up and see:

ERROR: network <name> declared as external, but could not be found

This means your Compose file references a network marked as external, but Docker cannot find a pre-existing network with that exact name. Compose does not create external networks for you.

Why it happens

• external: true tells Compose to attach to a network that already exists.
• If the named network does not exist, you get the error.
• Name mismatches are common. Compose-managed networks are prefixed by the project name (e.g., myproj_app_net). If you mark it external without matching the actual name, Compose won’t find it.

Quickstart fix

1. List networks and find the exact name you intend to use.
2. If missing, create the network.
3. Optionally update your Compose file to map the network name correctly.
4. Re-run docker compose up.

Commands

# 1) See existing networks
docker network ls

# 2) Create a user-defined bridge network if needed
docker network create app_net

# 3) Bring the stack up
docker compose up -d

Minimal working example

This example attaches a service to an external network named app_net that you must create beforehand.

version: "3.9"
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    networks:
      - app

networks:
  app:
    external: true
    name: app_net

Create the network and start the stack:

docker network create app_net
docker compose up -d

If you prefer Compose to manage the network automatically, remove external:

version: "3.9"
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    networks:
      - app

networks:
  app:
    driver: bridge

Then run:

docker compose up -d

Compose will create a network named <project>_app (project defaults to the directory name).

Common fixes and when to use them

Step-by-step diagnosis

1. Render the effective config to confirm network names.

   docker compose config
   

2. Inspect the project name Compose will use (defaults to folder name). Either specify one:

   docker compose -p myproj up -d
   

3. List networks and look for exact matches.

   docker network ls | grep -E "app_net|myproj_app|your_name"
   

4. Inspect a candidate network to verify the driver and scope.

   docker network inspect app_net
   

5. Update your Compose file:
   • If using an existing network: ensure external: true and name: matches docker network ls.
   • If letting Compose manage it: remove external and specify driver if needed.

Special cases

• Compose-generated networks: If another stack created myproj_app, your file should map to that exact name:

  networks:
    app:
      external: true
      name: myproj_app
  

  Or start with the same project name:

  docker compose -p myproj up -d
  

• Default bridge network: Do not mark it external by name bridge. Instead, prefer a user-defined bridge network for better DNS and isolation. If you must use the default bridge, do not declare it in Compose; services attach implicitly unless you set custom networks.

• Remote contexts: If using docker context use remote, the network must exist on that remote. Create it in the active context.

• Swarm overlay networks: If you reference an overlay network in Compose (non-Swarm), it likely won’t exist. Use a bridge network for local Compose or deploy to Swarm with docker stack deploy and a proper Swarm network.

Pitfalls to avoid

• Name typos or case differences. Docker network names are case-sensitive.
• Assuming Compose auto-creates external networks. It does not.
• Forgetting the project prefix when reusing networks between Compose projects.
• Using environment variable interpolation in network names without verifying the result (docker compose config helps).
• Mixing contexts or Docker Desktop/WSL2 backends where the network exists in one but not the active context.

Performance notes

• Prefer a single, shared user-defined bridge network for inter-service traffic across multiple Compose projects; it avoids duplicate networks and container reconnect overhead.
• User-defined bridge networks provide built-in DNS-based service discovery and typically perform well for local development.
• Overlay networks (Swarm/Kubernetes) add encryption/encapsulation overhead and are slower than local bridge networks; use only when you need multi-host networking.
• Avoid attaching containers to many networks unnecessarily; each additional network adds connection setup and iptables rules, which can slow container startup.

Tiny FAQ

• What does “external network” mean? A network that must already exist in Docker. Compose will not create or delete it.

• How do I share a network between multiple Compose projects? Create it once (docker network create shared_net) and set external: true with name: shared_net in each project.

• I see mydir_app in docker network ls. How do I reference it? Map it explicitly:

  networks:
    app:
      external: true
      name: mydir_app
  

  Or run with docker compose -p mydir up -d to match the prefix.

• Can I fix this by removing external: true? Yes, if you don’t need to share the network. Compose will create a project-scoped network automatically.

• Is it safe to reuse the default bridge network? It works, but a user-defined bridge is recommended for isolation, naming, and predictability.