multiple overlapping subnet configuration is not supported

Error message

multiple overlapping subnet configuration is not supported

What it means

Thrown by createIPAMConfig while populating subnets into the consolidation map. Each new subnet is compared against all previously added subnets via subnetMatches (bidirectional CIDR containment check at lines 148-156). If any two subnets overlap (one contains the other), the error fires because Docker's IPAM consolidation does not support overlapping CIDR ranges.

Solutions

Use mutually exclusive, non-overlapping CIDR blocks for each --subnet.
Verify with a subnet calculator that no specified range is contained within another.
Consolidate overlapping ranges into a single --subnet.

Example fix

# before
docker network create --subnet 172.20.0.0/16 --subnet 172.20.1.0/24 mynet
# after
docker network create --subnet 172.20.0.0/16 --subnet 172.21.0.0/16 mynet

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check subnets for overlap using netip before network create
func checkSubnetOverlap(subnets []string) error {
    var prefixes []netip.Prefix
    for _, s := range subnets {
        p, err := netip.ParsePrefix(s)
        if err != nil { return err }
        for _, q := range prefixes {
            if p.Overlaps(q) || q.Overlaps(p) {
                return fmt.Errorf("subnets %s and %s overlap", p, q)
            }
        }
        prefixes = append(prefixes, p)
    }
    return nil
}

Prevention

Plan CIDR ranges so no block nests inside another.
Use a subnet calculator or netip.Prefix.Overlaps in preflight checks.
Document each network's subnet allocation to avoid accidental reuse.

When it happens

Trigger: Running 'docker network create' with two --subnet flags whose CIDR blocks overlap, e.g. '--subnet 172.20.0.0/16 --subnet 172.20.1.0/24' where the /24 falls entirely inside the /16.

Common situations: Specifying a broad /16 plus a narrower /24 within it; copy-pasting subnet ranges from different configs that happen to nest; mixing IPv4 and IPv6 ranges carelessly.

Related errors

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

Appendix: source

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

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")
			}
		}
		sn, err := netip.ParsePrefix(s)
		if err != nil {
			return nil, err
		}
		iData[s] = &network.IPAMConfig{Subnet: sn, AuxAddress: map[string]netip.Addr{}}
	}

	// Validate and add valid ip ranges
	for _, r := range options.ipRanges {
		match := false
		for _, s := range options.subnets {
			ok, err := subnetMatches(s, r.String())
			if err != nil {
				return nil, err
			}
			if !ok {

View on GitHub (pinned to 4f84911bfe)