Docker Compose Network Not Found: Fix in 5 Minutes

Getting 'network not found' or 'network ... declared as external, but could not be found' from Docker Compose? Here is exactly how to diagnose and fix external network references, stale networks, and project name mismatches.

This error shows up in two flavors — a genuinely missing network, or Compose looking for the wrong network name because of a project-name mismatch. Here is how to tell which one you have.

Step 1: Read the Exact Error

bash

docker compose up
 
# ERROR: Network app_default declared as external, but could not be found.
# Please create the network manually using `docker network create app_default`
# and try again.

The network name Compose is looking for (app_default) tells you exactly what to check — it's either genuinely missing, or it exists under a slightly different name.

Cause 1: Network Genuinely Doesn't Exist Yet

bash

docker network ls | grep app_default
# (no output — confirmed missing)

Fix — create it:

bash

docker network create app_default
docker compose up

If the network is referenced as external: true in your compose file, Compose expects it to already exist — it will never create it for you.

yaml

networks:
  app_default:
    external: true    # Compose assumes this exists already

Cause 2: Project Name Mismatch (Most Common Cause)

Docker Compose prefixes network names with the project name — by default, the directory name your docker-compose.yml lives in. If you run Compose from a different directory, or with a different -p flag, the network name changes.

bash

# Yesterday, you ran this from /home/user/myapp/
docker compose up
# Created network: myapp_default
 
# Today, you ran it from /home/user/myapp-deploy/ (a symlink or renamed clone)
docker compose up
# Looking for: myapp-deploy_default   ← different name, "not found"

bash

# Check what project name Compose thinks it's using
docker compose config --format json | grep -i "name"
 
# List actual networks to compare
docker network ls

Fix — pin the project name explicitly so it's consistent regardless of directory:

yaml

# docker-compose.yml
name: myapp    # Explicit project name — Compose v2.20+

bash

# Or override at runtime
docker compose -p myapp up

This is the single most common cause in CI environments, where the checkout directory name can differ between local dev and the CI runner.

Cause 3: Network Was Removed by `docker compose down` But Referenced Elsewhere

bash

# If another compose file or a manually-run container references
# a network that a previous `docker compose down` already deleted:
docker compose down    # Removes networks not marked external
docker compose -f other-service/docker-compose.yml up
# ERROR: network myapp_default not found

docker compose down removes networks it created (non-external ones) by default — if a second, separate Compose project depends on the first project's network, that dependency breaks the moment the first project goes down.

Fix — make shared networks external and long-lived, not owned by any single Compose project:

bash

docker network create shared_backend

yaml

# Both compose files reference the same external network
networks:
  shared_backend:
    external: true

Cause 4: Compose File Syntax — Wrong Network Reference

yaml

# BAD — service references a network name that doesn't match
# the top-level networks: key
services:
  api:
    networks:
      - backend        # references "backend"
 
networks:
  app_backend:          # but it's actually defined as "app_backend"
    driver: bridge

bash

docker compose config    # Validates and shows the resolved config — catches this immediately

Fix — match the names exactly:

yaml

services:
  api:
    networks:
      - app_backend
 
networks:
  app_backend:
    driver: bridge

Verify the Fix

bash

docker compose config              # Confirms resolved network names, catches typos
docker network ls                  # Confirms what actually exists
docker compose up --remove-orphans # Clean start, removes stale containers from renamed networks

--remove-orphans is worth running after any project-name or network-naming fix — it clears out containers left behind under the old naming scheme that would otherwise silently keep running disconnected from your current stack.

More Docker troubleshooting? Read our Docker container keeps restarting fix and Docker build slow no cache fix.

Docker Compose Network Not Found: Fix in 5 Minutes

Step 1: Read the Exact Error

Cause 1: Network Genuinely Doesn't Exist Yet

Cause 2: Project Name Mismatch (Most Common Cause)

Cause 3: Network Was Removed by `docker compose down` But Referenced Elsewhere

Cause 4: Compose File Syntax — Wrong Network Reference

Verify the Fix

Stay ahead of the curve

Related Articles

AWS ECR Image Push Access Denied — Every Fix (2026)

AWS ECR Push Denied: no basic auth credentials — Fix

AWS ECS Task Keeps Stopping — How to Fix It (2026)

Comments