Maaz Zindani

Loading the index…

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

Compose rejects a service that has both network_mode and networks

Error'network_mode' and 'networks' cannot be combined

Short answer

Compose does not allow network_mode and networks on the same service. network_mode picks one fixed networking setup, such as host, none or another service's stack, so a list of networks has no meaning next to it. Delete one of the two. To join custom networks while sharing a stack, put the networks on the service you point to.

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

Fix it fast

  1. 1Find out which cause you have

    Render the merged configuration and find which service carries both keys. Overrides and extends files can add the second key without it being visible in the main file.

    docker compose config | grep -n -E "^  [a-z0-9_-]+:$|network_mode|networks:"
  2. 2Match what you see, then jump to its fix

    1. 1The error appears at docker compose up or config, before any container startsBoth keys are set on the same serviceFix
    2. 2network_mode: service:web together with networks: on the sidecarA sidecar shares another service's network but also wants its own networksFix
    3. 3networks: [] or an empty networks key, next to network_mode: noneYou wanted a service with no network and used an empty networks listFix

What does the error look like?

  • 'network_mode' and 'networks' cannot be combined

Cause 1 of 3

Both keys are set on the same service

1Check

Open the service in the rendered output. The Compose reference says that when network_mode is set, the networks attribute is not allowed and Compose rejects the file.

docker compose config --services

2Fix

Decide which one you need. If the service must sit on your own named networks, delete network_mode. If it needs a special mode, delete networks.

services:
  app:
    image: my-app
    networks: [backend]     # no network_mode here

3Verify

Validate the file.

docker compose config -q && echo ok

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

A sidecar shares another service's network but also wants its own networks

1Check

With network_mode: service:NAME the container uses the network stack of that service, so it has the same addresses and ports. Your own networks list is not applicable.

grep -n -B2 -A2 'network_mode: service' compose.yaml

2Fix

Attach the networks to the service being shared. The sidecar joins them automatically because it shares that stack.

services:
  web:
    image: nginx
    networks: [backend]
  sidecar:
    image: my-sidecar
    network_mode: "service:web"

3Verify

Start the project and list which networks the web container holds.

docker compose up -d
docker inspect --format '{{json .NetworkSettings.Networks}}' $(docker compose ps -q web)

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

You wanted a service with no network and used an empty networks list

1Check

An empty or missing networks attribute makes Compose attach the service to the default network. It does not remove networking.

docker compose config | grep -n -A3 'network_mode'

2Fix

Use network_mode: none on its own to turn off container networking.

services:
  batch:
    image: my-batch
    network_mode: none

3Verify

The container should have no network interface besides loopback.

docker compose run --rm batch cat /proc/net/dev

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Run docker compose config -q in CI so a conflicting pair fails before deploy.
  • Remember that ports cannot be published with network_mode: host; the Compose reference says port mapping must not be used with it.
  • When you split config into override files, search all of them for network_mode before adding networks.

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.