When working with multi-container applications, you might encounter the “network not found” error when running docker-compose up. This prevents your containers from starting and communicating with each other. This guide explains why this happens and provides clear steps to resolve it.

The Error

The error typically looks like this when you execute docker-compose up:

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

Or, in newer Docker Compose V2 versions:

Error response from daemon: network my_custom_network not found

Root Cause

This issue is almost always related to how networks are defined in your docker-compose.yml file. The most common causes are:

  1. External Network Missing: You have declared a network with external: true in your compose file, but you haven’t actually created that network in Docker yet.
  2. Typo in Network Name: There is a mismatch between the name of the network declared in the compose file and the actual network created in Docker.
  3. Orphaned Networks: Sometimes, if Docker was restarted abruptly or a previous teardown failed, Docker’s internal networking state can become desynchronized.
  4. Different Docker Contexts: You created the network in one Docker context (like a remote host) but are running compose against another (like your local machine).

Step-by-Step Solution

Step 1: Verify the Network Exists

First, check if the network Docker Compose is looking for actually exists. Run the following command in your terminal:

docker network ls

Look for the network name mentioned in the error message. If it’s not in the list, then it hasn’t been created.

Step 2: Create the External Network

If your docker-compose.yml expects an external network (often used so multiple distinct compose projects can talk to each other), you must create it manually before starting the containers.

Create the network using:

docker network create my_custom_network

(Replace my_custom_network with the name from your error message).

After creating it, run docker-compose up -d again. It should now work perfectly.

Step 3: Modify docker-compose.yml for Automatic Creation

If you don’t actually need the network to be shared with other independent compose projects, you can let Docker Compose manage it automatically.

Open your docker-compose.yml and look at the networks block at the bottom:

networks:
  my_custom_network:
    external: true

Change it to simply specify the driver, or remove the external flag so Docker creates it for you:

networks:
  my_custom_network:
    driver: bridge

Note: If Docker Compose creates the network automatically, it will prefix the network name with the project directory name (e.g., myproject_my_custom_network).

Step 4: Clean Up Docker Networks (If the network should exist but is glitching)

If docker network ls shows the network, but Docker Compose still claims it cannot be found, your Docker network state might be corrupted.

You can clear out unused Docker networks and try again:

docker network prune

(Warning: This will remove all custom networks not currently used by at least one container).

Alternative Solution: Specifying the Network Name Explicitly

If you’re using Docker Compose V2 and want to force a specific network name without using external: true, you can use the name property:

networks:
  my_custom_network:
    name: my_explicit_network_name
    driver: bridge

This tells Docker Compose to create the network with that exact name, ignoring the usual folder-prefix convention.

Prevention

To avoid this error in the future:

  • Document External Dependencies: If your project requires an external network, document it clearly in your README.md file.
  • Use Initialization Scripts: For complex setups, provide a setup.sh or Makefile target that runs docker network create ... || true before running docker-compose up.
  • Avoid External When Not Needed: Keep networks internal to the compose file unless you explicitly need them to span across separate deployments.

Summary

  • The “network not found” error means Docker Compose is trying to attach containers to a network that doesn’t exist.
  • It usually happens when external: true is set in the compose file, but the network wasn’t created manually.
  • Fix it by creating the network beforehand with docker network create <name>.
  • Alternatively, remove external: true to let Docker Compose handle network creation automatically.