How to Fix Docker Compose 'network not found' Error

In this tutorial, you'll learn about How to Fix Docker Compose 'network not found' Error. We cover key concepts, practical examples, and best practices.

The Problem

Running <a href="/devops/docker-compose/">docker compose</a> up fails with network "myproject_default" not found or network "shared-net" declared as external but could not be found because the network referenced in the compose file does not exist.

Quick Fix

Create an External Network First

docker network create shared-net
# abc1234def5678
docker compose up -d
# [+] Running 2/2
#  ✔ Container web   Started
#  ✔ Container api   Started

When a compose file references an external network, you must create it manually with docker network create before starting the services.

Let Compose Create the Network Automatically

node -e "
const compose = {
    services: {
        app: { image: 'nginx' }
    }
    // no explicit networks — Compose creates 'project_default'
};
console.log('Remove external: true from network config to let Compose auto-create');
"
# Remove external: true from network config to let Compose auto-create

If you remove the external: true flag, Docker Compose creates the network automatically on up. This is the simplest fix for a missing network.

Clean Up Orphaned Networks

docker network prune -f
# Deleted Networks:
# myproject_default
# oldproject_default
docker compose up -d
# [+] Running 1/1
#  ✔ Network myproject_default   Created

Orphaned networks with the same name as your project's network can interfere. Run docker network prune to remove unused networks and let Compose recreate them.

Inspect Existing Networks

docker network ls
# NETWORK ID     NAME              DRIVER    SCOPE
# abc1234        shared-net        bridge    local
# def5678        bridge            bridge    local
docker network inspect shared-net
# [
#     {
#         "Name": "shared-net", "#         "Scope": "local"", "#         "Driver": "bridge"",
#     }
# ]

List all networks to verify the name and driver match what your compose file expects.

Use <a href="/devops/docker-compose/">docker compose</a> up --force-recreate to Rebuild Networks

docker compose down -v
docker compose up --force-recreate -d
# [+] Running 3/3
#  ✔ Network myproject_default   Created

The -v flag removes volumes (use cautiously). The --force-recreate flag ensures networks are rebuilt even if compose thinks they already exist, which resolves stale network references.

Inspect Container Configuration

docker inspect <container-id> --format '{{json .Config}}' | python3 -m json.tool
# {
#   "Hostname": "abc123",
#   "Env": ["PATH=/usr/local/bin:..."],
#   "Cmd": ["node", "app.js"]
# }

Use docker inspect to examine the full configuration of a container. This reveals misconfigurations in environment variables, command arguments, and network settings that may not appear in logs.

Additional Troubleshooting

# Check the error message and stack trace for more context
echo "Review the full error output to identify the root cause"

If the above steps do not resolve the issue, examine the complete error message and stack trace. Often the key detail is in the middle of the traceback rather than the final line. Search for the error message in the project documentation or issue tracker for additional solutions.

Prevention

• Create external networks with docker network create before running <a href="/devops/docker-compose/">docker compose</a> up
• Use <a href="/devops/docker-compose/">docker compose</a> down to clean up project networks when they are no longer needed
• Specify driver and driver_opts in your compose file to match the expected network configuration
• Use network: host or network: none when services do not need bridge networking