🚨 Docker Error Guide: 'Network declared as external, but could not be found' — Compose

Overview

Compose refuses to start because a network you told it already exists does not:

Network frontend declared as external, but could not be found. Please create the network manually using `docker network create frontend` and try again.

Marking a network external: true is a promise to Compose: this network already exists, do not create or manage it — just attach to it. When Compose looks up that network by name and the daemon has no matching network, it fails fast rather than silently creating one. The fix is either to create the network first or to stop declaring it external.

Symptoms

• docker compose up aborts before any container starts, naming a specific external network.
• The network exists but under a different real name than Compose is looking for (project-prefix confusion).
• The stack works on a host where the network was pre-created, and fails on a fresh host.
• A shared “reverse-proxy” or “frontend” network is missing after a docker system prune removed it.
• docker network ls does not list the name Compose reports as missing.

Common Root Causes

• The external network was never created. external: true requires you (or another stack) to create it out-of-band first.
• Name mismatch. Compose looks up the exact name: you gave; a typo or a different casing means “not found” even though a similar network exists.
• Project-prefix assumptions. Without an explicit name:, Compose may look for a differently-prefixed name than the one you created manually.
• The network was pruned. docker network prune or docker system prune removed an unused shared network between runs.
• Wrong Docker context or host. The network exists on one host/context but you are deploying against another.

Diagnostic Workflow

List the networks the daemon actually has and compare names exactly:

docker network ls

See what network name Compose has resolved for the project:

docker compose config

A typical external-network declaration — Compose will look up the literal name: value:

services:
  web:
    image: registry.example.com/myapp:1.4.2
    networks:
      - frontend

networks:
  frontend:
    external: true
    name: frontend          # must match an existing network exactly

If the network is genuinely missing, create it once, then bring the stack up:

docker network create frontend
docker network ls | grep frontend
docker compose up -d

If instead you want Compose to own the network, remove external: true so Compose creates and manages it automatically:

networks:
  frontend:
    driver: bridge

Example Root Cause Analysis

An organization ran several independent Compose stacks (an API, a worker, a web app) that all needed to reach a shared Traefik reverse proxy. The proxy’s Compose file created a network named edge, and every other stack declared:

networks:
  edge:
    external: true
    name: edge

This worked until a nightly cleanup job ran docker system prune -f on the host. Because no container was attached to edge at that moment (a brief maintenance window had stopped the proxy), prune removed the unused network. When the API stack redeployed, Compose reported Network edge declared as external, but could not be found.

The immediate fix was docker network create edge followed by restarting the proxy and dependent stacks. The durable fix was twofold: mark the network as non-prunable by keeping the proxy running, and add docker network create edge || true to the deployment bootstrap so the shared network is always guaranteed to exist before any stack that references it as external.

Prevention Best Practices

• Create shared external networks in a bootstrap step, e.g. docker network create edge || true, so referencing stacks never race against a missing network.
• Pin the network name: explicitly on both the creating and the consuming side so lookups match regardless of project prefixes.
• Keep at least one container attached to shared networks, or exclude them from cleanup, so docker network prune cannot remove them.
• Only use external: true for networks you manage elsewhere. If a stack owns its network, let Compose create it and skip the external flag.
• Verify with docker network ls as part of your deploy checklist; see the Docker stack guides for shared-network patterns.

Quick Command Reference

# List existing networks
docker network ls

# Create the external network Compose expects
docker network create frontend

# Idempotent create for bootstrap scripts
docker network create edge || true

# See the name Compose resolves for the project
docker compose config

# Start after the network exists
docker compose up -d

Conclusion

Network declared as external, but could not be found means Compose was told a network already exists but the daemon has no match. Decide who owns the network: if it is shared, create it up-front (idempotently) and match the name: exactly on both sides; if the stack owns it, drop external: true and let Compose create it. A docker network ls check in your deploy flow keeps this error from ever reaching production.