docker compose refuses a service that points to a network that was never declared
ERROR: 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.
Fix it fast
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/null2Match what you see, then jump to its fix
- 1
The 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
A networks: block exists, yet the error still names a network that looks the sameThe networks block is nested wrongly or spelled differentlyFix - 3
You 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
- 1
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.yaml2Fix
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=backendConfirmed by docs.docker.com
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.yaml2Fix
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 OKConfirmed by github.com
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 ls2Fix
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-proxy3Verify
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
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
Servers
docker compose rejects a service that uses a volume nobody declared
Undefined volume with Docker Compose
A short volume entry like data:/var/lib/data names a volume called data.
3 causes, each with a fixServers
Docker says the network you named does not exist
Error response from daemon: network myapp not found
A container or Compose file refers to a network name the daemon does not have.
3 causes, each with a fixServers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fix