cannot configure multiple ranges

Error message

cannot configure multiple ranges (%s, %s) on the same subnet (%s)

What it means

Returned by `createIPAMConfig` (network/create.go:179-182) when two or more `--ip-range` values fall within the SAME declared `--subnet`. The IPAM consolidation stores one IPRange per subnet, so a second range on the same subnet is rejected. The message names the conflicting ranges and the subnet.

Solutions

Declare a separate --subnet for each --ip-range so each range maps to its own subnet.
Merge multiple ranges into a single larger --ip-range if they must share one subnet.
Use --aux-address for reserving specific IPs rather than additional ranges.
Re-read the IPAM consolidation model: positions of --subnet and --ip-range are correlated by index/containment.

Example fix

# before
docker network create --subnet 172.20.0.0/16 \
  --ip-range 172.20.1.0/24 --ip-range 172.20.2.0/24 net
# after
docker network create --subnet 172.20.1.0/24 --ip-range 172.20.1.0/25 \
  --subnet 172.20.2.0/24 --ip-range 172.20.2.0/25 net

Defensive patterns

Strategy: validation

Validate before calling

// ensure at most one ip-range per subnet before creating the network
seen := map[string]bool{}
for _, r := range ipRanges {
    for _, s := range subnets {
        ok, _ := subnetMatches(s, r.String())
        if ok {
            if seen[s] { return fmt.Errorf("two ranges on subnet %s", s) }
            seen[s] = true
        }
    }
}

Try / catch

if err := runCreate(ctx, c, out, options); err != nil {
    if strings.Contains(err.Error(), "cannot configure multiple ranges") {
        return fmt.Errorf("%w — give each range its own --subnet", err)
    }
    return err
}

Prevention

Map each --ip-range to a distinct --subnet.
Merge overlapping ranges into one.
Use --aux-address for individual reservations instead of extra ranges.

When it happens

Trigger: Running `docker network create --subnet 172.20.0.0/16 --ip-range 172.20.1.0/24 --ip-range 172.20.2.0/24 net` — both ranges are inside the single /16 subnet.

Common situations: Misunderstanding that one subnet maps to one range; trying to carve multiple sub-ranges under one subnet via repeated --ip-range flags.

Related errors

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

Appendix: source

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

		}
		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 {
				continue
			}

			// Using "IsValid" to check if a valid IPRange was already set.
			if iData[s].IPRange.IsValid() {
				return nil, fmt.Errorf("cannot configure multiple ranges (%s, %s) on the same subnet (%s)", r.String(), iData[s].IPRange.String(), s)
			}
			if ipRange, ok := toPrefix(r); ok {
				iData[s].IPRange = ipRange
				match = true
			}
		}
		if !match {
			return nil, fmt.Errorf("no matching subnet for range %s", r.String())
		}
	}

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

View on GitHub (pinned to 4f84911bfe)