{"record":{"id":"f07dd5ae60e49a23","repo":"docker/cli","slug":"every-ip-range-or-gateway-must-have-a-correspondin","errorCode":null,"errorMessage":"every ip-range or gateway must have a corresponding subnet","messagePattern":"every ip-range or gateway must have a corresponding subnet","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/network/create.go","lineNumber":141,"sourceCode":"\t\tLabels:     opts.ConvertKVStringsToMap(options.labels.GetSlice()),\n\t})\n\tif err != nil {\n\t\treturn err\n\t}\n\t_, _ = fmt.Fprintln(output, resp.ID)\n\treturn nil\n}\n\n// Consolidates the ipam configuration as a group from different related configurations\n// user can configure network with multiple non-overlapping subnets and hence it is\n// possible to correlate the various related parameters and consolidate them.\n// createIPAMConfig consolidates subnets, ip-ranges, gateways and auxiliary addresses into\n// structured ipam data.\n//\n//nolint:gocyclo\nfunc createIPAMConfig(options ipamOptions) (*network.IPAM, error) {\n\tif len(options.subnets) < len(options.ipRanges) || len(options.subnets) < len(options.gateways) {\n\t\treturn nil, errors.New(\"every ip-range or gateway must have a corresponding subnet\")\n\t}\n\tiData := map[string]*network.IPAMConfig{}\n\n\t// Populate non-overlapping subnets into consolidation map\n\tfor _, s := range options.subnets {\n\t\tfor k := range iData {\n\t\t\tok1, err := subnetMatches(s, k)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, err\n\t\t\t}\n\t\t\tok2, err := subnetMatches(k, s)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, err\n\t\t\t}\n\t\t\tif ok1 || ok2 {\n\t\t\t\treturn nil, errors.New(\"multiple overlapping subnet configuration is not supported\")\n\t\t\t}\n\t\t}","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/network/create.go#L123-L159","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add a --subnet flag (CIDR) for every --ip-range and --gateway you specify.","Ensure the number of --subnet flags is >= both the number of --ip-range and --gateway flags.","Remove orphaned --gateway/--ip-range flags that have no corresponding subnet."],"exampleFix":"# before\ndocker network create --gateway 10.0.0.1 mynet\n# after\ndocker network create --subnet 10.0.0.0/24 --gateway 10.0.0.1 mynet","handlingStrategy":"validation","validationCode":"// Validate IPAM option counts before calling runCreate/createIPAMConfig\nfunc validateIPAMCounts(ipam ipamOptions) error {\n    if len(ipam.subnets) < len(ipam.ipRanges) || len(ipam.subnets) < len(ipam.gateways) {\n        return fmt.Errorf(\"need at least %d --subnet flags to cover ip-ranges/gateways\",\n            max(len(ipam.ipRanges), len(ipam.gateways)))\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair every --gateway and --ip-range with an explicit --subnet in CIDR form.","In wrappers/scripts, assert len(subnets) >= max(len(ipRanges), len(gateways)) before invoking the CLI.","Treat a missing --subnet as a configuration error, not a default to auto-pick."],"tags":["network","ipam","docker","go","cli"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}