Tech Digest

Guide

Docker Compose "network was found but has incorrect label com.docker.compose.network"

Compose found a network with the name it wanted, but the network's label says a different compose key owns it, or that no Compose made it at all. We reproduced each cause on Compose 2.35.1, then ran the same files on 5.4.0 and 5.8.0, which no longer stop.

Last reviewed

How do you fix Docker Compose "network was found but has incorrect label com.docker.compose.network set to"?

Read the value after "set to". If it is "", the network was made by hand with docker network create: add external: true under that network if it is meant to be shared, or remove it with docker network rm and let Compose recreate it. If it is a name, another compose file or an older version of yours owns the network under that key: mark it external: true in every file but one, or run docker compose down, remove the network, and run up -d again. Compose 5.4.0 and later only warn.

Compose found a network with the name it wanted, but the network belongs to someone else. Read the value in quotes after "set to". An empty value, "", means no compose file made the network: someone ran docker network create. A name, such as "web", means a compose file made it under that key, and yours uses a different key.

A network meant to be shared gets external: true in your file. A network that is just in the way gets removed while nothing uses it, and Compose makes a fresh one.

The terms this answer turns on#

A Compose project is one stack: the containers, networks and volumes from one compose file. Its name comes from the folder, unless -p, COMPOSE_PROJECT_NAME or a top-level name: sets it.

Each network in a compose file has a key and a name. The key is the word under networks: in your file, such as default, web or proxy. The name is what Docker calls the network. By default the name is the project name plus the key, so myapp_default. If you set name: under the network, the docs say it "is used as is and is not scoped with the project name".

A label is a note stuck on a Docker object, a key and a value. Compose writes three on every network it creates. com.docker.compose.project holds the project name, and com.docker.compose.network holds the key from the compose file.

An external network is one Compose uses but does not own. The reference says Compose "doesn't attempt to create these networks, and returns an error if one doesn't exist".

The check itself, in Compose 2.35.1's resolveOrCreateNetwork, finds the network by name and compares its com.docker.compose.network label with your key. A different project label only earns a warning. Issue 10797 says why the check exists. Maintainer ndeloof wrote that earlier versions "may select a network 'by name' that is not the expected one (name unicity is not enforced by docker engine) resulting in weird bugs".

Two answers circulate, and both are half right#

The first answer is "run docker network prune" or "downgrade to 2.18.1". Prune also removes every other unused network on the host. In our test it removed a network whose only container was stopped, and that container could not start again. Downgrading works, because 2.18.1 has no check, and brings back the bug the check was added for.

The second answer is "relabel the network". Docker cannot change a network's labels, so this means delete and recreate. That is right for a leftover network and wrong for a shared one.

Which versions throw it#

Compose versionWhat happens
2.18.1 and earlierNo check. The network is used by name
2.19.0 (21 June 2023) to 2.29.xError, without the (expected: ...) part
2.30.0 (29 October 2024) to 5.3.1Error, with (expected: "key")
5.4.0 (3 August 2026) and laterWarning only, network reused

The check arrived with PRs 10612 and 10639, both in the 2.19.0 release notes. Threads often say 2.19.1, because issue 10797 was filed against it. Commit 0723f710, dated 27 July 2026, removed the error, and 5.4.0 is the first release with it. Its message says Compose now finds "legacy/unlabeled networks by name" and reuses them "untouched".

What we measured#

We ran each case on Docker Engine 28.1.1 with Compose 2.35.1, 5.3.1, 5.4.0 and 5.8.0, the latest release (17 November 2026). Our test names all start with nlab.

Case2.35.1 and 5.3.15.4.0 and 5.8.0
docker network create of the project's default network nameError, set to "" (expected: "default")Warning, network reused
Shared network made by hand, declared with name: but not externalError, set to "" (expected: "default")Warning, network reused
Second project, same network name:, different keyError, set to "web" (expected: "frontend")Warning, network reused
Network key renamed in your own file, name: keptError, set to "zabbix" (expected: "backend")not run
Renamed project folderWorks. A second network is createdWorks, same
Two folders with the same top-level name:Works. Orphan warning onlyWorks, same
Network made by docker-compose 1.29.2Works. Labels matchnot run

The full error on 2.35.1 came with a warning line first:

text
level=warning msg="a network with name nlab-proxy exists but was not created by compose.\nSet `external: true` to use an existing network"
network nlab-proxy was found but has incorrect label com.docker.compose.network set to "" (expected: "default")

The docker-compose 1.29.2 network carried the same labels Compose v2 writes, so it passed. A renamed folder is a new project with new network names, so it passes too. Its real damage is the old stack running beside the new one, which Why Docker says port is already allocated shows on ports.

Read the two quoted values#

The error saysWhat made the networkFix
set to "" and the network should be shareddocker network create, by you or a guideexternal: true under that network
set to "" and nothing else needs itA leftover from a test or another toolRemove what uses it, docker network rm, then up -d
set to "a" (expected: "b"), another stack uses itAnother compose file, under key aexternal: true in every file but the owner's
set to "a" (expected: "b"), only your stack uses itYour own file, before the key was renameddocker compose down, docker network rm, then up -d

Before you remove a network, see who made it and what is on it, running or stopped:

bash
docker network inspect NAME --format '{{json .Labels}}'
docker ps -a --filter network=NAME --format '{{.Names}}\t{{.Status}}\t{{.Label "com.docker.compose.project"}}'

Fix 1: a shared network made by hand#

This is the common one. A guide tells you to run docker network create proxy for a reverse proxy. A stack copied from somewhere else names that network but leaves out external. Mark it external:

yaml
networks:
  default:
    name: proxy
    external: true

On 2.35.1 that started with no warning, and docker compose down left the network for the other stacks. If the network is missing, Compose stops with network proxy declared as external, but could not be found, so create it once, by hand.

Fix 2: a leftover network in the way#

If nothing needs the network, remove it and let Compose make its own. Docker refuses while a container is running on it:

text
Error response from daemon: error while removing network: network nlabh_default has active endpoints (nlab-hand)

Remove that container first with docker rm -f, then run docker network rm NAME and docker compose up -d. The new network carried all three Compose labels.

Stopping is not enough. A stopped container does not block docker network rm, but it still points at the old network. We ran docker compose stop, removed the network, and ran up -d. Compose made a new network, then failed with failed to set up container networking: network 1f9c0dae... not found. up -d --force-recreate fixed it, because it makes new containers. Running docker compose down first avoids the problem.

Giving your network a different name: also works, and leaves the old one behind. If you are recreating networks anyway, Docker subnet clashes and address pools covers which subnets they will get.

Fix 3: two compose files claim one network#

Two stacks can both declare name: shared. The first up creates it with its own key. The second stack uses a different key and hits the error. Pick one stack as the owner. In every other file, mark the network external: true. On 2.35.1 the second stack then started cleanly.

That makes order matter. The owner's down removes the network if nothing else is on it. The other stacks then stop with network shared declared as external, but could not be found until the owner is back. A network made by hand, as in fix 1, has no owner and no such ordering.

Fix 4: you renamed the network key#

Renaming the key under networks: while keeping name: leaves the label at the old key. On 2.35.1, docker compose down with the edited file removed the container but not the network, so the next up failed the same way. Running docker network rm after down fixed it, and the new network carried the new key. Renaming the key back works too.

A close variant is one file that gives two keys the same name:, such as default and net1 both named net1. In issue 10797, ndeloof's answer to that was to "just don't use 2 entries to define a single network". Keep one key, and point services at it.

What Compose 5.4.0 and later do instead#

They reuse the network and print a warning from warnUnmanagedNetworks in the current source. It says the network "was not created for project" yours, or "was not created by compose" if it has no labels. Then it adds "Set external: true to use an existing network". Every such run exited 0.

That is quieter, not safer. In the two-projects case, 5.4.0 and 5.8.0 joined the second project's containers to the first project's network. On 5.8.0, when the first project ran down, the network stayed, and Compose printed Resource is still in use. The second project's down left it too, because it was never that project's. The fixes above still apply. With them in place, the warning is gone as well.

A worked case: a new app beside a reverse proxy#

Take a host where Caddy runs on a network made with docker network create proxy. You add a dashboard whose sample compose file ends with networks: default: name: proxy. Suppose your Compose is 2.35.1.

docker compose up -d would print the warning, then network proxy was found but has incorrect label com.docker.compose.network set to "" (expected: "default"). The empty value says the network was made by hand. The name proxy says it is shared. That is fix 1: add external: true under it and run up -d again.

Suppose instead the value were "caddy". Then Caddy's own compose file made the network under that key. That is fix 3, and the answer is the same line in the dashboard's file. Do not remove the network in either case. Caddy is on it, and Docker would refuse anyway.

When this answer stops applying#

This was measured on Docker Engine 28.1.1 on Linux, with the Compose versions named above. We did not test Docker Desktop, Podman, Swarm overlay networks or Compose 2.19.0 itself. The 2.19 to 2.29 message form comes from reading the source, not from running it. Version 5.4.0 was not run on the renamed-key case or the v1 network. A later Compose may change the warnings, so match on "incorrect label" and on "was not created", not on whole lines.

What to do next#

Read the value after "set to", then pick the row in the table above. Give every stack a fixed top-level name:, as Docker Compose conventions recommends, so a folder rename cannot make a second copy. If the stack sits behind a proxy, Reverse proxy and TLS has the shared network layout that avoids most of this.

Questions#

Which Docker Compose version added the incorrect label error?

Compose 2.19.0, released 21 June 2023. It shipped PR 10612, "detect network conflict as name is not guaranteed to be unique", and PR 10639, which wrote this message. Many threads say 2.19.1, because the issue that made it famous was filed on 2.19.1, but the check is already in 2.19.0. Compose 2.30.0 added the (expected: ...) part. Compose 5.4.0, released 3 August 2026, removed the error.

Does docker network prune fix it?

Only when the network has no running container, and it removes more than you meant. In our test on Engine 28.1.1, prune removed a network whose only container was stopped, and that container then failed to start with network ... not found. Prune also removes every other unused network on the host, including a shared proxy network while its stacks are down. Remove the one network by name with docker network rm instead.

Does renaming the project folder cause this error?

No. A renamed folder is a new project, so its default network gets a new name and Compose simply creates it. We renamed a folder on Compose 2.35.1 and got two networks, no error. If the network has a fixed name:, the renamed project reuses it with a warning that it "was not created for project". The rename still causes trouble, as a second copy of the stack holding the same ports.

Does upgrading Docker Compose make the error go away?

Yes, from 5.4.0. That release finds the network by name and reuses it, with a warning that it "was not created by compose" or "was not created for project". The problem the check caught is still there. In our test two projects ended up on one network, and the first project's down left it behind as "Resource is still in use". Set external: true anyway, so the warning goes away for a reason.

What does set to "" mean in the error?

The network has no com.docker.compose.network label at all, so Compose did not create it. The usual source is docker network create, often run from a guide that sets up a shared proxy network. The compose file then names the same network without external: true, so Compose expects to own it. Add external: true under that network and the error stops.

Can I add the Compose labels to an existing network?

No. Docker has no command that changes a network's labels after it is created. You can delete it and create it again with --label com.docker.compose.network=default --label com.docker.compose.project=myapp. On Compose 2.35.1 that passed the check, but Compose then treats the network as its own, and docker compose down removed it. Use that only if the project really should own the network.

Sources#

Published . Last reviewed . Found something out of date? Tell us and we will fix it and log the change.