Victor's room

Overview & Root Cause Summary: The error network <network_name> declared as external but could not be found occurs when executing docker compose up (or docker-compose up) on a project whose docker-compose.yml file references an external bridge or overlay network. Unlike default networks, Docker Compose will not automatically provision networks declared with external: true, expecting them to already exist in the Docker daemon before startup.

Understanding the Root Causes

• Uncreated External Network: The Compose file explicitly defines a shared network (such as traefik_proxy, web_gateway, or db_network) with external: true, but no previous command or container has created it on the host.
• Accidental Network Pruning: Executing cleanup commands like docker network prune or docker system prune -a removed inactive external networks that had no running containers attached.
• Compose v1 vs Compose v2 Syntax and Naming Discrepancies: Older Compose specifications relied on default project prefixes (e.g. myproject_default). If an external network was created without an explicit name, Compose may look for a differently prefixed network identifier.
• CI/CD Ephemeral Runner Environments: Fresh container build runners (GitHub Actions, GitLab CI) launch in clean states where prerequisite shared networks have not been initialized prior to deploying the service stack.

Step 1: Quick Fix (Create the Missing External Network via CLI)

Directly initialize the missing bridge network using the Docker CLI so Compose can attach to it immediately.

# 1. Check existing Docker networks on your system:
docker network ls

# 2. Create the missing network using the exact name specified in the error:
docker network create my_external_network

# (Optional: If using custom driver options or subnets):
# docker network create --driver bridge --subnet 172.28.0.0/16 my_external_network

# 3. Re-run your Docker Compose stack:
docker compose up -d

Step 2: Correct Compose File Syntax (Compose v2 vs v1 Formats)

Ensure your docker-compose.yml declares the external network using modern Compose Specification standards to prevent naming ambiguities.

# Modern Compose Specification (Recommended for Docker Compose v2):
services:
  web:
    image: nginx:alpine
    networks:
      - custom_shared_net

networks:
  custom_shared_net:
    name: my_external_network  # The exact name registered in 'docker network ls'
    external: true

# Legacy Compose v1 format (Alternative):
# networks:
#   my_external_network:
#     external: true

Step 3: Automated Shell Scripts and CI/CD Pre-Creation Checks

Incorporate an idempotent pre-launch check in your deployment scripts or Makefile to automatically instantiate the external network if missing.

# Bash One-Liner (Idempotent: Creates network only if it does not already exist):
docker network inspect my_external_network >/dev/null 2>&1 || \
    docker network create my_external_network

# Example in a Makefile:
deploy:
	@docker network inspect my_external_network >/dev/null 2>&1 || \
		(echo "Creating external network..." && docker network create my_external_network)
	docker compose up -d --build

# In GitHub Actions workflow (.github/workflows/deploy.yml):
# - name: Ensure External Docker Network Exists
#   run: docker network inspect my_external_network || docker network create my_external_network

Verification & Testing Steps

Confirm network attachment and verify inter-container communication across the external bridge.

# 1. Verify that the network is listed and active:
docker network ls | grep my_external_network

# 2. Inspect the network to confirm your Compose containers are attached:
docker network inspect my_external_network
# Look under the "Containers" object for your service container names and allocated IPs.

# 3. Test service reachability:
docker compose ps
docker compose logs --tail=20

Summary Comparison Table