{"record":{"id":"5f86aea3e39682ac","repo":"docker/cli","slug":"cannot-configure-multiple-ranges-s-s-on-the-s","errorCode":null,"errorMessage":"cannot configure multiple ranges (%s, %s) on the same subnet (%s)","messagePattern":"cannot configure multiple ranges \\((.+?), (.+?)\\) on the same subnet \\((.+?)\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/network/create.go","lineNumber":181,"sourceCode":"\t\t}\n\t\tiData[s] = &network.IPAMConfig{Subnet: sn, AuxAddress: map[string]netip.Addr{}}\n\t}\n\n\t// Validate and add valid ip ranges\n\tfor _, r := range options.ipRanges {\n\t\tmatch := false\n\t\tfor _, s := range options.subnets {\n\t\t\tok, err := subnetMatches(s, r.String())\n\t\t\tif err != nil {\n\t\t\t\treturn nil, err\n\t\t\t}\n\t\t\tif !ok {\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\t// Using \"IsValid\" to check if a valid IPRange was already set.\n\t\t\tif iData[s].IPRange.IsValid() {\n\t\t\t\treturn nil, fmt.Errorf(\"cannot configure multiple ranges (%s, %s) on the same subnet (%s)\", r.String(), iData[s].IPRange.String(), s)\n\t\t\t}\n\t\t\tif ipRange, ok := toPrefix(r); ok {\n\t\t\t\tiData[s].IPRange = ipRange\n\t\t\t\tmatch = true\n\t\t\t}\n\t\t}\n\t\tif !match {\n\t\t\treturn nil, fmt.Errorf(\"no matching subnet for range %s\", r.String())\n\t\t}\n\t}\n\n\t// Validate and add valid gateways\n\tfor _, g := range options.gateways {\n\t\tmatch := false\n\t\tfor _, s := range options.subnets {\n\t\t\tok, err := subnetMatches(s, g.String())\n\t\t\tif err != nil {\n\t\t\t\treturn nil, err","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/network/create.go#L163-L199","documentation":"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.","triggerScenarios":"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.","commonSituations":"Misunderstanding that one subnet maps to one range; trying to carve multiple sub-ranges under one subnet via repeated --ip-range flags.","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."],"exampleFix":"# before\ndocker network create --subnet 172.20.0.0/16 \\\n  --ip-range 172.20.1.0/24 --ip-range 172.20.2.0/24 net\n# after\ndocker network create --subnet 172.20.1.0/24 --ip-range 172.20.1.0/25 \\\n  --subnet 172.20.2.0/24 --ip-range 172.20.2.0/25 net","handlingStrategy":"validation","validationCode":"// ensure at most one ip-range per subnet before creating the network\nseen := map[string]bool{}\nfor _, r := range ipRanges {\n    for _, s := range subnets {\n        ok, _ := subnetMatches(s, r.String())\n        if ok {\n            if seen[s] { return fmt.Errorf(\"two ranges on subnet %s\", s) }\n            seen[s] = true\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := runCreate(ctx, c, out, options); err != nil {\n    if strings.Contains(err.Error(), \"cannot configure multiple ranges\") {\n        return fmt.Errorf(\"%w — give each range its own --subnet\", err)\n    }\n    return err\n}","preventionTips":["Map each --ip-range to a distinct --subnet.","Merge overlapping ranges into one.","Use --aux-address for individual reservations instead of extra ranges."],"tags":["network","ipam","subnet","ip-range","validation","docker-cli"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}