Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker compose refuses a service that points to a network that was never declared

ErrorERROR: Service "web" uses an undefined network "backend"

Short answer

Every network name a service lists must also exist under the top-level networks key, except default, which Compose creates for you. If the name is missing there, misspelled or nested in the wrong place, Compose refuses the file. Declare it next to services, match the spelling, or mark it external when another project owns it.

  • Applies to Docker Compose v2, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check the file on its own. The message names the service and the network, so compare that name with the keys under the top-level networks block.

    docker compose config --quiet
    grep -n -E '^networks:|^  *networks:|^services:' compose.yaml docker-compose.yml 2>/dev/null
  2. 2Match what you see, then jump to its fix

    1. 1The services block has networks: - backend, and no networks: block at the left edge of the file mentions backendThe network is listed by a service but never declaredFix
    2. 2A networks: block exists, yet the error still names a network that looks the sameThe networks block is nested wrongly or spelled differentlyFix
    3. 3You want this service to join a network that another Compose project or a docker network create command already madeThe network belongs to another project and should be externalFix

What does the error look like?

  • ERROR: Service "web" uses an undefined network "backend"
  • service "web" refers to undefined network backend

Cause 1 of 3

The network is listed by a service but never declared

1Check

Each service gets access through its own networks list, and every name in that list has to be defined in the top-level networks element. The only network Compose adds on its own is default.

grep -n -E 'backend' compose.yaml

2Fix

Add the name at top level. An empty entry is enough: Compose then creates the network with default settings.

services:
  web:
    image: example/webapp
    networks:
      - backend
  db:
    image: postgres:17
    networks:
      - backend

networks:
  backend:

3Verify

The file resolves, and the project network appears after the next up.

docker compose config --quiet && echo OK
docker compose up -d && docker network ls --filter name=backend

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The networks block is nested wrongly or spelled differently

1Check

The top-level networks key has to sit at the left edge, as a sibling of services. Under a service, networks means something else: the list that service joins. Names are compared as written, so Backend and backend are two networks.

grep -n -i -E 'backend' compose.yaml

2Fix

Move the block to the left edge and use one spelling everywhere.

services:
  web:
    image: example/webapp
    networks:
      - back-tier

networks:       # same indentation as services
  back-tier:

3Verify

Compose parses the file.

docker compose config --quiet && echo OK

Confirmed by github.com

Did this fix it?

Cause 3 of 3

The network belongs to another project and should be external

1Check

A network that is not managed by this file must be declared with external: true. Compose then does not create it, and returns an error if it does not exist, so check that it exists first.

docker network ls

2Fix

Create the network once if it is missing, then declare it as external, with name if the real name differs from the key.

docker network create shared-proxy

# compose.yaml
services:
  web:
    image: example/webapp
    networks:
      - outside

networks:
  outside:
    external: true
    name: shared-proxy

3Verify

The service starts and is attached to the existing network.

docker compose up -d
docker network inspect shared-proxy --format '{{range .Containers}}{{.Name}} {{end}}'

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Declare a network in the same commit that first uses it.
  • Use short, lower-case network names and copy them instead of retyping them.
  • Run docker compose config --quiet in CI so a missing declaration fails before a deploy.
  • Do not list networks on a service that uses network_mode: Compose rejects the combination.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.