docker/cli · error

every ip-range or gateway must have a corresponding subnet

Error message

every ip-range or gateway must have a corresponding subnet

What it means

Raised by createIPAMConfig in `docker network create` when the count of --ip-range or --gateway flags exceeds the count of --subnet flags. Each ip-range and gateway must be nested inside a declared subnet, so the CLI rejects the configuration up front before calling the NetworkCreate API.

Source

Thrown at cli/command/network/create.go:141

		Labels:     opts.ConvertKVStringsToMap(options.labels.GetSlice()),
	})
	if err != nil {
		return err
	}
	_, _ = fmt.Fprintln(output, resp.ID)
	return nil
}

// Consolidates the ipam configuration as a group from different related configurations
// user can configure network with multiple non-overlapping subnets and hence it is
// possible to correlate the various related parameters and consolidate them.
// createIPAMConfig consolidates subnets, ip-ranges, gateways and auxiliary addresses into
// structured ipam data.
//
//nolint:gocyclo
func createIPAMConfig(options ipamOptions) (*network.IPAM, error) {
	if len(options.subnets) < len(options.ipRanges) || len(options.subnets) < len(options.gateways) {
		return nil, errors.New("every ip-range or gateway must have a corresponding subnet")
	}
	iData := map[string]*network.IPAMConfig{}

	// Populate non-overlapping subnets into consolidation map
	for _, s := range options.subnets {
		for k := range iData {
			ok1, err := subnetMatches(s, k)
			if err != nil {
				return nil, err
			}
			ok2, err := subnetMatches(k, s)
			if err != nil {
				return nil, err
			}
			if ok1 || ok2 {
				return nil, errors.New("multiple overlapping subnet configuration is not supported")
			}
		}

View on GitHub (pinned to e9452d6e78)

Solutions

1. Add a --subnet flag for every --ip-range and --gateway you pass (e.g. --subnet 10.0.0.0/16 --gateway 10.0.0.1)
2. Remove stray --gateway/--ip-range flags if you want Docker's default IPAM allocation
3. For dual-stack networks, declare both the IPv4 and IPv6 subnets before their respective gateways

Example fix

# before
docker network create --gateway 10.0.0.1 mynet
# after
docker network create --subnet 10.0.0.0/16 --gateway 10.0.0.1 mynet

When it happens

Trigger: Running `docker network create` with len(ipRanges) > len(subnets) or len(gateways) > len(subnets), e.g. `docker network create --gateway 10.0.0.1 mynet` with no --subnet, or two --ip-range flags but one --subnet.

Common situations: Scripts that template out gateway/ip-range flags but forget the subnet; copy-pasted compose-to-CLI translations; adding an IPv6 gateway without adding the matching IPv6 subnet.

Related errors

• multiple overlapping subnet configuration is not supported
• network prune has been cancelled
• conflicting options: cannot attach both user-defined and non
• conflicting options: cannot specify both --network-alias and
• conflicting options: cannot specify both --link and per-netw

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/f07dd5ae60e49a23.json. Report an issue: GitHub.