startContainer(%s): incompatible network_mode and networks c

Error message

startContainer(%s): incompatible network_mode and networks config

What it means

startContainer validates network settings before creating the container: if the service sets network_mode to 'none' or 'host' while also defining entries under `networks:`, the configuration is contradictory (those modes bypass custom networks), so it returns 'startContainer(%s): incompatible network_mode and networks config'.

Source

Thrown at pkg/app/master/compose/execution.go:1321

				log.Debugf("startContainer(): service network config - %s", name)
				if _, ok := activeNetworks[name]; ok {
					netMode = activeNetworks[name].Name
					netModeKey = name
					log.Debugf("startContainer(): found active network config - %s (netMode=%s)", name, netMode)
					break
				}
			}
		}

		if netMode == "" {
			netMode = "none"
			log.Debug("startContainer(): default netMode to none")
		}
	}

	if (netMode == "none" || netMode == "host") && len(service.Networks) > 0 {
		log.Debugf("startContainer(%s): incompatible network_mode and networks config", service.Name)
		return "", fmt.Errorf("startContainer(%s): incompatible network_mode and networks config", service.Name)
	}

	netAliases := []string{
		service.Name,
	}

	if len(service.Networks) != 0 {
		netConfig, ok := service.Networks[netModeKey]
		if ok && netConfig != nil {
			netAliases = append(netAliases, netConfig.Aliases...)
		}
	}

	endpointsConfig := map[string]*dockerapi.EndpointConfig{
		netMode: {
			Aliases: netAliases,
		},
	}

View on GitHub (pinned to 81940d17fa)

Solutions

Remove the `networks:` section from the service if host/none networking is intended
Remove or change `network_mode: host`/`none` if custom networks are required (use a bridged network instead)
Fix override/merge files so they clear conflicting keys, e.g. set networks: {} when overriding network_mode

Example fix

// before (docker-compose.yml)
  monitor:
    network_mode: host
    networks:
      - backend      # incompatible with host networking
// after
  monitor:
    network_mode: host
    # networks removed

Defensive patterns

Strategy: validation

Validate before calling

func checkNetworkCompat(svc types.ServiceConfig) error {
    if (svc.NetworkMode == "host" || svc.NetworkMode == "none") && len(svc.Networks) > 0 {
        return fmt.Errorf("service %q: network_mode %q incompatible with networks %v",
            svc.Name, svc.NetworkMode, svc.Networks)
    }
    return nil
}

Try / catch

_, err := execution.StartService(ctx, svcName)
if err != nil {
    if strings.Contains(err.Error(), "incompatible network_mode and networks config") {
        return fmt.Errorf("fix compose file: drop networks or network_mode for %q: %w", svcName, err)
    }
    return err
}

Prevention

When setting network_mode: host or none, remove the networks section
Review override/merge files for conflicting network keys
Use `docker compose config` to inspect the merged final config before deploying

When it happens

Trigger: Deploying/starting a service whose compose config has `network_mode: host` or `network_mode: none` together with a non-empty `networks:` mapping/list.

Common situations: Merging compose fragments where one sets network_mode: host and another adds custom networks; copying a host-networking snippet into a service that already used custom networks; override files that don't clear the networks key.

Related errors

AI-assisted analysis of slimtoolkit/slim@81940d17fa (2026-08-31). Data as JSON: /api/errors/9c5073c23439e008. Report an issue: GitHub.