Fix docker-network-not-found: Resolve Docker Compose 'network not found' errors

The docker-network-not-found error typically occurs when Docker Compose attempts to start services that are configured to use a specific network, but that network is either not defined within the docker-compose.yml file or does not exist as an external network on the Docker host. This issue prevents containers from being created and communicating as intended, leading to a failed deployment of your multi-container application. Understanding the various ways networks are declared and managed in Docker Compose is crucial for resolving this common problem.

1. Symptoms: Clear description of indicators and shell output.

When encountering the docker-network-not-found error, you will typically observe the docker-compose up command failing with a clear error message indicating that a specific network cannot be found. The process will halt, and no containers will be started or become accessible.

Here’s a typical output you might see:

$ docker-compose up

ERROR: Network "my_custom_network" not found.

In this example, my_custom_network is the name of the network that Docker Compose failed to locate. The error message explicitly states which network is missing, which is key to diagnosing the problem. You might also notice that other services that depend on this network will not start, and docker ps will show no new containers related to your project.

2. Root Cause: Technical explanation of the underlying cause.

The docker-network-not-found error primarily stems from a mismatch between the network configuration specified in your docker-compose.yml file and the actual state of networks on your Docker host. There are several common scenarios that lead to this error:

1. Undefined Network in docker-compose.yml: The most frequent cause is referencing a network name within a service definition (e.g., under networks:) that is not subsequently defined at the top-level networks: section of the docker-compose.yml file. Docker Compose needs to know how to create or connect to this network.
2. Missing External Network: If you declare a network as external: true in your docker-compose.yml, Docker Compose expects this network to already exist on the Docker host. If the network has not been manually created using docker network create <network_name> prior to running docker-compose up, the error will occur. This is common in production environments where networks might be pre-provisioned.
3. Typographical Errors: A simple typo in the network name, either in the service’s networks: section or in the top-level networks: definition, can lead to Docker Compose searching for a non-existent network.
4. Incorrect docker-compose.yml Context: Running docker-compose up from a directory where the intended docker-compose.yml file is not present, or where a different, incomplete configuration file is being picked up, can also cause this error if the active configuration lacks proper network definitions.
5. Project Name Mismatch: While less common for this specific error, if you’re using a custom project name (e.g., via -p flag or COMPOSE_PROJECT_NAME environment variable) and referencing networks that implicitly rely on the default project name, it can sometimes lead to confusion, though Docker Compose usually handles this gracefully by prefixing network names.

In essence, the error indicates that Docker Compose cannot establish the necessary network infrastructure because the instructions for doing so are either incomplete, incorrect, or refer to a resource that doesn’t exist.

3. Step-by-Step Fix: Accurate fix instructions. You MUST use “Before:” and “After:” labels for code comparison blocks.

Resolving the docker-network-not-found error involves reviewing your docker-compose.yml file and ensuring that all referenced networks are correctly defined or pre-existing.

Step 1: Identify the Missing Network From the error message, note the exact name of the network that Docker Compose reported as “not found.” For example, if the error is ERROR: Network "my_custom_network" not found., then my_custom_network is the target.

Step 2: Review Your docker-compose.yml Configuration

Open your docker-compose.yml file and examine the networks: section at the top level and how services reference networks.

Scenario A: The network should be defined within the docker-compose.yml (most common).

If you intend for Docker Compose to create and manage the network as part of your project, it must be explicitly defined under the top-level networks: key.

Before:

version: '3.8'
services:
  web:
    image: nginx
    ports:
      - "80:80"
    networks:
      - my_custom_network # Referenced but not defined
  app:
    image: myapp
    networks:
      - my_custom_network

After:

version: '3.8'
services:
  web:
    image: nginx
    ports:
      - "80:80"
    networks:
      - my_custom_network
  app:
    image: myapp
    networks:
      - my_custom_network

networks:
  my_custom_network: # Network is now defined
    driver: bridge

Explanation: By adding my_custom_network: under the top-level networks: key, you instruct Docker Compose to create a bridge network with that name for your project.

Scenario B: The network is intended to be external (pre-existing).

If you want your services to connect to a network that already exists on your Docker host (e.g., a network shared across multiple projects or manually created), you must declare it as external: true. If the network doesn’t exist, you’ll need to create it first.

Before:

version: '3.8'
services:
  web:
    image: nginx
    ports:
      - "80:80"
    networks:
      - existing_shared_network # Declared external, but network doesn't exist
networks:
  existing_shared_network:
    external: true

Explanation: In this case, docker-compose expects existing_shared_network to already be present. If it’s not, the error occurs.

After: First, manually create the external network:

docker network create existing_shared_network

Then, your docker-compose.yml remains the same:

version: '3.8'
services:
  web:
    image: nginx
    ports:
      - "80:80"
    networks:
      - existing_shared_network
networks:
  existing_shared_network:
    external: true

Explanation: By running docker network create, you ensure the external network exists before docker-compose attempts to use it.

Scenario C: Typographical Error.

Carefully check for any misspellings in network names. This applies to both the service’s networks: entry and the top-level networks: definition.

Before:

version: '3.8'
services:
  web:
    image: nginx
    networks:
      - my_custom_network # Typo here
networks:
  my_custum_network: # Correctly defined, but name mismatch
    driver: bridge

After:

version: '3.8'
services:
  web:
    image: nginx
    networks:
      - my_custum_network # Corrected to match definition
networks:
  my_custum_network:
    driver: bridge

Explanation: Ensure consistent naming across all references to the same network.

4. Verification: How to confirm the fix works.

After applying the necessary changes to your docker-compose.yml file or creating the external network, you can verify the fix by attempting to start your Docker Compose project again.

1. Run docker-compose up: Navigate to the directory containing your docker-compose.yml file and execute:

   docker-compose up -d
   

   The -d flag runs the containers in detached mode, allowing you to continue using your terminal. If the fix is successful, you should see output indicating that services are being created and started, without the “network not found” error.

2. Check Running Containers: Verify that all expected containers are running using docker ps:

   docker ps
   

   You should see your services listed with a Status of Up.

3. Inspect Networks: Confirm that the network(s) you defined or referenced are correctly created and associated with your project:

   docker network ls
   

   Look for your network name (e.g., yourprojectname_my_custom_network for an internal network, or existing_shared_network for an external one).

4. Test Connectivity (Optional but Recommended): If your application exposes ports or has internal communication, try accessing it. For example, if a web service is exposed on port 80:

   curl http://localhost:80
   

   Or, if you have multiple services, try to ping one from another (e.g., docker exec -it <web_container_id> ping app). Successful communication confirms the network setup is functional.

5. Common Pitfalls: Key mistakes to avoid.

When dealing with Docker Compose networks, several common mistakes can lead to the docker-network-not-found error or similar networking issues:

1. Forgetting to Define Internal Networks: A very common oversight is to reference a network name under a service’s networks: key without providing a corresponding definition in the top-level networks: section. Docker Compose cannot magically infer how to create a network if it’s only mentioned in a service. Always ensure internal networks are explicitly defined.
2. Not Creating External Networks: When external: true is used, it’s a firm instruction to Docker Compose that the network must already exist. Forgetting to run docker network create <network_name> beforehand will inevitably lead to this error. This is particularly crucial in automated deployment pipelines where network provisioning might be a separate step.
3. Typographical Errors: Simple typos in network names are surprisingly frequent. A single character difference between the service’s networks: entry and the top-level networks: definition (or the actual external network name) will cause the error. Double-check all network names for consistency.
4. Running docker-compose from the Wrong Directory: If you execute docker-compose up from a directory other than where your docker-compose.yml file resides, Docker Compose might not find your configuration, or it might pick up an unintended, incomplete configuration. Always ensure you are in the correct project root.
5. Misunderstanding Default Networking: Docker Compose automatically creates a default network for your project if no custom networks are defined. While convenient, relying solely on this can sometimes lead to confusion when you later decide to introduce custom networks and forget to define them properly.
6. Case Sensitivity: While Docker often normalizes network names, it’s best practice to maintain consistent casing. Inconsistent casing, especially for external networks, can sometimes lead to unexpected “not found” errors. Stick to lowercase and hyphens for network names for maximum compatibility.

Avoiding these pitfalls requires careful attention to your docker-compose.yml configuration and a clear understanding of how Docker Compose manages networks, both internal and external.

6. Related Errors: 2-3 similar errors.

Understanding errors related to docker-network-not-found can help in broader Docker Compose troubleshooting, as they often point to similar configuration or environmental issues.

1. docker-compose-service-not-found: This error occurs when a service attempts to reference another service by name, but the referenced service is either misspelled, not defined in the docker-compose.yml, or not part of the same network. It’s analogous to docker-network-not-found but for services rather than networks, highlighting issues with inter-service communication setup.
2. docker-container-port-conflict: While not directly about networks being “not found,” this error often arises from incorrect network configurations, specifically when multiple containers try to bind to the same host port. It indicates a problem with how services are exposed or how their network settings are managed, often requiring adjustments to ports mappings or ensuring services are on isolated networks if necessary.
3. docker-network-already-exists: This error is the inverse of docker-network-not-found. It occurs when Docker Compose tries to create a network that already exists, typically when an external: true declaration is missing for a pre-existing network, or when a previous docker-compose up run was interrupted, leaving behind a network. It points to a misunderstanding of network lifecycle management within Docker Compose.