How to Fix 'network not found' Docker Error

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

The Problem

You run docker run --network my-network ... or docker-compose up and get Error: network my-network not found or network <name> was found but has incorrect scope: local. The Docker network you're trying to use doesn't exist or is in the wrong scope. This happens when your compose file references a custom network that hasn't been created yet, or when a Swarm overlay network is referenced from a non-Swarm context.

Quick Fix

1. List existing networks

docker network ls

Expected output:

NETWORK ID     NAME      DRIVER    SCOPE
abc123def456   bridge    bridge    local
789ghi012jkl   host      host      local
345mno678pqr   none      null      local

If your network isn't in this list, it doesn't exist yet.

2. Create the missing network

docker network create my-network

By default this creates a bridge network on local scope, which works for single-host container communication.

Verify creation:

docker network ls | grep my-network

3. Connect a running container to the network

docker network connect my-network my-container

This attaches an existing container to the network without restarting it. Use this when you need to connect a container that's already running and you don't want to lose its state.

4. Run a new container on the network

docker run -d --name app --network my-network nginx:alpine

Containers on the same bridge network can communicate using container names as hostnames. For example, from another container on my-network, you can reach this one at http://app:80.

5. For Docker Compose, define the network in compose.yml

services:
  app:
    image: nginx:alpine
    networks:
      - my-network
  db:
    image: postgres:16
    networks:
      - my-network

networks:
  my-network:
    driver: bridge

Then run <a href="/devops/docker-compose/">docker compose</a> up and Compose creates the network automatically. If you get the error with Compose, run <a href="/devops/docker-compose/">docker compose</a> down first to remove any partially-created resources, then <a href="/devops/docker-compose/">docker compose</a> up again.

6. Create an overlay network for Docker Swarm

docker network create --driver overlay --attachable my-overlay-net

The --attachable flag allows non-Swarm containers to use the overlay network too. Without it, only Swarm services can connect.

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.

Prevention

• Always define networks in compose.yml under the top-level networks: key — don't rely on external networks unless they're explicitly created
• Check network scope (docker network ls --filter scope=swarm) when using Docker Swarm — overlay networks require swarm mode to be active
• Remove unused networks regularly with docker network prune to avoid name conflicts
• Use docker network inspect my-network to view connected containers and driver details when troubleshooting