{"record":{"id":"2914548f73c04608","repo":"docker/cli","slug":"cannot-configure-multiple-gateways-s-s-for-th","errorCode":null,"errorMessage":"cannot configure multiple gateways (%s, %s) for the same subnet (%s)","messagePattern":"cannot configure multiple gateways \\((.+?), (.+?)\\) for the same subnet \\((.+?)\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/network/create.go","lineNumber":205,"sourceCode":"\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\n\t\t\t}\n\t\t\tif !ok {\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tif iData[s].Gateway.IsValid() {\n\t\t\t\treturn nil, fmt.Errorf(\"cannot configure multiple gateways (%s, %s) for the same subnet (%s)\", g, iData[s].Gateway, s)\n\t\t\t}\n\t\t\td := iData[s]\n\t\t\td.Gateway = toNetipAddr(g)\n\t\t\tmatch = true\n\t\t}\n\t\tif !match {\n\t\t\treturn nil, fmt.Errorf(\"no matching subnet for gateway %s\", g)\n\t\t}\n\t}\n\n\t// Validate and add aux-addresses\n\tfor name, aa := range options.auxAddresses.GetAll() {\n\t\tif aa == \"\" {\n\t\t\tcontinue\n\t\t}\n\t\tauxAddr, err := netip.ParseAddr(aa)\n\t\tif err != nil {\n\t\t\treturn nil, err","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/network/create.go#L187-L223","documentation":"Returned by createIPAMConfig when consolidating IPAM gateway configuration during `docker network create`. Each subnet may have at most one gateway; once a gateway IP is assigned to a subnet's IPAMConfig (iData[s].Gateway.IsValid()), attempting to assign a second gateway whose IP falls inside the same subnet triggers this error. It enforces the 1:1 subnet-to-gateway invariant the daemon's IPAM driver expects.","triggerScenarios":"Passing two or more --gateway flags where the supplied gateway IPs both resolve (via subnetMatches) to the same --subnet. For example: `docker network create --subnet 172.20.0.0/16 --gateway 172.20.0.1 --gateway 172.20.0.2 net`. The second gateway hits iData[s].Gateway.IsValid()==true at create.go:204.","commonSituations":"Mistakenly specifying both an IPv4 and IPv6 gateway for the same CIDR, copy-pasting a gateway flag twice, or assuming the second --gateway replaces rather than augments the first. Also occurs when overlapping subnets are intended but the user forgets that gateways are matched by containment.","solutions":["Remove duplicate --gateway flags so each subnet has exactly one gateway.","If you need two gateways, put them on two distinct non-overlapping --subnet declarations (e.g. separate IPv4 and IPv6 subnets).","Let IPAM auto-assign the gateway by omitting --gateway entirely for subnets that do not need an explicit one."],"exampleFix":"// before\ndocker network create --subnet 172.20.0.0/16 --gateway 172.20.0.1 --gateway 172.20.0.2 net\n// after\ndocker network create --subnet 172.20.0.0/16 --gateway 172.20.0.1 net","handlingStrategy":"validation","validationCode":"// Before building the create request, ensure at most one gateway per subnet.\nfunc validateGateways(subnets []string, gateways []net.IP) error {\n    type seen struct{}\n    assigned := make(map[string]seen) // subnet string -> has gateway\n    for _, s := range subnets {\n        _, ipn, err := net.ParseCIDR(s)\n        if err != nil { return err }\n        for _, g := range gateways {\n            if ipn.Contains(g) {\n                if _, ok := assigned[s]; ok {\n                    return fmt.Errorf(\"subnet %s already has a gateway\", s)\n                }\n                assigned[s] = seen{}\n            }\n        }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Maintain one --gateway per --subnet; track them in a single config structure.","When scripting, build a map[subnet]gateway and error on duplicate keys before invoking docker.","Prefer omitting --gateway to let IPAM auto-assign unless you need a specific address."],"tags":["network","ipam","gateway","docker-cli"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}