Docker Compose: network not found

Hi, it's BlueByte. You run docker compose up on a project that worked yesterday and it stops with a network-not-found error — either network <name> declared as external, but could not be found, or Error response from daemon: network <hash> not found as it tries to start a container. Your compose file didn't change; a network your containers expect isn't there anymore. We'll walk through both message forms, how Compose names and creates its networks, why one goes missing, how to see what's actually there, and how to fix each case.

The two "network not found" messages Compose prints

Two distinct situations produce this. The first is a missing external network:

network shared_net declared as external, but could not be found

Your compose file marks a network external: true, which tells Compose to attach to a network it does not manage — and that network doesn't exist yet. The second is a dangling network reference:

Error response from daemon: network 7b2a...f31 not found

Here Compose, or a container it created earlier, still refers to a network by ID that has since been deleted. You'll hit this on docker compose up, down, start, or restart — the stored reference points at a network the daemon no longer has.

How Compose names and creates its default network

When you run docker compose up, Compose creates a network named <project>_default and attaches every service to it. The project name comes from the directory holding the compose file, unless you override it:

docker compose -p myproj up -d       # or set COMPOSE_PROJECT_NAME=myproj

[+] Running 2/2
 ✔ Network myproj_default   Created
 ✔ Container myproj-web-1   Started

So myapp_default belongs to the myapp project. If you rename the directory or change the project name, Compose starts looking for a differently named network — a common reason a network seems to "vanish" when nothing was actually deleted.

Why the network went missing

The reference breaks for a few concrete reasons:

• Someone ran docker network prune or docker network rm, removing a network that stopped containers still point to.
• The Docker daemon or host restarted and a network wasn't recreated the way the old container metadata expects.
• The compose file declares an external: true network that was never created, or was created under a different name.
• The project name changed — a renamed directory or an added -p — so Compose now looks for newname_default while the containers live on oldname_default.

See what networks exist and what your project expects

List what the daemon actually has, then confirm what your compose file asks for:

docker network ls
docker compose config --networks

docker network ls shows every network by name and ID; docker compose config --networks prints the networks your merged compose file expects. If a name in the second list isn't in the first, that's your gap. To see which network a stuck container is pinned to:

docker inspect -f '{{json .NetworkSettings.Networks}}' myproj-web-1

Fix the dangling network: bring it down, then recreate

For the dangling-reference case, tear the project down and let Compose rebuild the network. --remove-orphans also clears containers left over from a previous project name:

docker compose down --remove-orphans
docker compose up -d

If down itself fails with the same network error, force the containers to be recreated so they re-attach to a fresh network:

docker compose up -d --force-recreate

 ✔ Network myproj_default   Created
 ✔ Container myproj-web-1   Recreated

Fix a missing external network: create it first

An external: true network must exist before docker compose up. Create it once, then bring the project up:

docker network create shared_net
docker compose up -d

The name has to match exactly. If your compose file gives the network a custom name:, create that name, not the key:

networks:
  shared_net:
    external: true
    name: company_shared

Here you must run docker network create company_shared — Compose looks up company_shared, and shared_net is only the local alias.

A real case: a pruned network after a host reboot

A small stack had been up for weeks. After a host reboot I ran docker system prune to reclaim space, which removed the stopped project's network. docker compose up -d then failed with network 7b2a...f31 not found. docker network ls confirmed myproj_default was gone. docker compose down --remove-orphans cleared the stale references, docker compose up -d recreated myproj_default and re-attached both containers, and the stack was back — no compose file edits, just resetting the project's networking to a clean state.

How it differs from "network already exists" and "port is already allocated"

network not found is the absence case — Compose expects a network that isn't there. network <name> ... already exists is the opposite: a leftover network with the same name blocks creation, cleared with docker network rm. Bind for 0.0.0.0:8080 failed: port is already allocated has nothing to do with networks — a published host port is held by another process. Reading which of the three you got tells you whether to create a network, remove one, or free a port.