docker/cli · error

multiple overlapping subnet configuration is not supported

Error message

multiple overlapping subnet configuration is not supported

What it means

Raised in createIPAMConfig while consolidating subnets: each new --subnet is checked against those already collected with subnetMatches in both directions, and if either contains the other the CLI aborts. Docker's IPAM cannot represent two overlapping subnets on one network.

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 e9452d6e78)

Solutions

1. Make the subnets disjoint CIDRs (e.g. 10.0.0.0/24 and 10.1.0.0/24) or remove the duplicate
2. If you wanted a sub-allocation range inside one subnet, use --ip-range with the single parent --subnet instead of a second --subnet
3. Create separate networks if the workloads genuinely need overlapping address spaces

Example fix

# before
docker network create --subnet 10.0.0.0/16 --subnet 10.0.1.0/24 mynet
# after
docker network create --subnet 10.0.0.0/16 --ip-range 10.0.1.0/24 mynet

When it happens

Trigger: `docker network create` with two --subnet values where one CIDR contains or equals the other, e.g. --subnet 10.0.0.0/16 --subnet 10.0.1.0/24, or the same subnet listed twice.

Common situations: Merging config fragments that each add a subnet; typos in prefix length (e.g. /16 vs /24) causing accidental containment; duplicating a subnet when adding an ip-range that was meant to go inside it.

Related errors

• every ip-range or gateway must have a corresponding subnet
• 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/4357c1c18bef1f5c.json. Report an issue: GitHub.