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

Thrown by createIPAMConfig during 'docker network create' when the count of --subnet flags is smaller than the count of --ip-range or --gateway flags (line 140). Each IP range and gateway must be associated with a subnet so the CLI can determine which network segment it belongs to; without a matching subnet the IPAM config cannot be consolidated.

Solutions

1. Add a --subnet flag (CIDR) for every --ip-range and --gateway you specify.
2. Ensure the number of --subnet flags is >= both the number of --ip-range and --gateway flags.
3. Remove orphaned --gateway/--ip-range flags that have no corresponding subnet.

Example fix

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

// Validate IPAM option counts before calling runCreate/createIPAMConfig
func validateIPAMCounts(ipam ipamOptions) error {
    if len(ipam.subnets) < len(ipam.ipRanges) || len(ipam.subnets) < len(ipam.gateways) {
        return fmt.Errorf("need at least %d --subnet flags to cover ip-ranges/gateways",
            max(len(ipam.ipRanges), len(ipam.gateways)))
    }
    return nil
}

When it happens

Trigger: Running 'docker network create' with more --ip-range or --gateway flags than --subnet flags. The guard is len(subnets) < len(ipRanges) || len(subnets) < len(gateways), so e.g. '--gateway 10.0.0.1' with zero --subnet flags, or one --subnet with two --gateway flags.

Common situations: Forgetting to add --subnet when specifying a custom --gateway; assuming the gateway value implies its subnet; specifying multiple gateways/ranges for a single subnet without realizing each needs an explicit subnet entry.

Related errors

• multiple overlapping subnet configuration is not supported
• network prune has been cancelled
• node ID not found in /info
• cannot supply extra formatting options to the pretty…
• context must be a directory

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

Appendix: 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 4f84911bfe)