Docker Compose "service refers to undefined network" in CI

By Kaveh Alemi·Latchkey

Every network a service attaches to under its networks: key must be declared in the top-level networks: section. Naming a network on a service without declaring it makes Compose fail config validation with refers to undefined network.

What this error means

A docker compose up/config fails with service "<name>" refers to undefined network "<net>". The network is used but not declared at the top level.

service "api" refers to undefined network "backend": invalid compose project

Common causes

A network used but not declared

A service lists backend under its networks: but there is no top-level networks: backend: entry.

A typo between service and top-level network names

Mismatched names mean the referenced network is effectively undefined.

How to fix it

Declare the network at the top level

1. Add the network to the top-level networks: section.
2. Keep the names identical to the service reference.

services:
  api:
    networks: [backend]
networks:
  backend:
    driver: bridge

Align the network names

1. Fix any typo so the service reference matches a declared network.

networks:
  backend: {}
  frontend: {}

How to prevent it

• Declare every referenced network at the top level.
• Keep service and top-level network names identical.
• Validate with docker compose config in CI.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation