docker/cli · error

undefined network

Error message

undefined network %q

What it means

Returned by convertServiceNetworks when a service lists a network that is neither defined in the top-level networks map nor the implicit 'default' network (service.go:210-214). Swarm conversion refuses to attach a service to a network it cannot resolve.

Solutions

1. Add the referenced network to the top-level `networks:` block.
2. If the network already exists in Docker, declare it with `external: true`.
3. Fix the typo in the service's network name to match a defined network.

Example fix

// before
services:
  web:
    image: nginx
    networks: [frontnet]
// after
services:
  web:
    image: nginx
    networks: [frontnet]
networks:
  frontnet:

// Ensure every network referenced by a service is declared (or is 'default').
func validateNetworks(cfg *composetypes.Config) error {
    for _, svc := range cfg.Services {
        for name := range svc.Networks {
            if name == "default" {
                continue
            }
            if _, ok := cfg.Networks[name]; !ok {
                return fmt.Errorf("undefined network %q", name)
            }
        }
    }
    return nil
}

When it happens

Trigger: A service's `networks:` references a name that has no matching entry in the top-level `networks:` block and is not 'default'. Reached at service.go:212 when networkConfigs[networkName] is absent and networkName != defaultNetwork.

Common situations: Renamed a network in one section only; copy-pasted a service that uses a network never added to the file; merged two compose files where the network definition lives in a file that wasn't included.

Related errors

• undefined secret
• undefined config
• service
• invalid restart policy: unknown policy
• unknown mode

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/f99c141668dbcf9e. Report an issue: GitHub.

Appendix: source

Thrown at cli/compose/convert/service.go:213

}

func convertServiceNetworks(
	networks map[string]*composetypes.ServiceNetworkConfig,
	networkConfigs networkMap,
	namespace Namespace,
	name string,
) ([]swarm.NetworkAttachmentConfig, error) {
	if len(networks) == 0 {
		networks = map[string]*composetypes.ServiceNetworkConfig{
			defaultNetwork: {},
		}
	}

	nets := make([]swarm.NetworkAttachmentConfig, 0, len(networks))
	for networkName, nw := range networks {
		networkConfig, ok := networkConfigs[networkName]
		if !ok && networkName != defaultNetwork {
			return nil, fmt.Errorf("undefined network %q", networkName)
		}
		var aliases []string
		var driverOpts map[string]string
		if nw != nil {
			aliases = nw.Aliases
			driverOpts = nw.DriverOpts
		}
		target := namespace.Scope(networkName)
		if networkConfig.Name != "" {
			target = networkConfig.Name
		}
		netAttachConfig := swarm.NetworkAttachmentConfig{
			Target:     target,
			Aliases:    aliases,
			DriverOpts: driverOpts,
		}
		// Only add default aliases to user defined networks. Other networks do
		// not support aliases.

View on GitHub (pinned to 4f84911bfe)