{"record":{"id":"ed9d167145d7f7a6","repo":"docker/cli","slug":"no-matching-subnet-for-gateway-s","errorCode":null,"errorMessage":"no matching subnet for gateway %s","messagePattern":"no matching subnet for gateway (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/network/create.go","lineNumber":212,"sourceCode":"\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\n\t\t}\n\t\tmatch := false\n\t\tfor _, s := range options.subnets {\n\t\t\tok, err := subnetMatches(s, auxAddr.String())\n\t\t\tif err != nil {\n\t\t\t\treturn nil, err\n\t\t\t}","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/network/create.go#L194-L230","documentation":"Returned by createIPAMConfig when a --gateway IP does not fall inside any of the configured --subnet CIDRs. The loop at create.go:194-213 iterates all subnets and sets match=true only when subnetMatches returns true; if no subnet contains the gateway, the command fails. This prevents handing the daemon a gateway that belongs to no managed address space.","triggerScenarios":"Supplying a --gateway whose address is outside every --subnet. For example: `docker network create --subnet 172.20.0.0/16 --gateway 10.0.0.1 net`, or specifying only --gateway without a matching --subnet.","commonSituations":"CIDR prefix typos (wrong octet), copying a gateway from another network's config, mixing up which subnet a gateway belongs to, or forgetting to declare the IPv6 subnet when adding an IPv6 gateway.","solutions":["Verify the gateway IP is numerically contained in one of the --subnet CIDRs.","Add the missing --subnet that contains the intended gateway.","Drop the explicit --gateway and let IPAM pick the first usable host address automatically."],"exampleFix":"// before\ndocker network create --subnet 172.20.0.0/16 --gateway 10.0.0.1 net\n// after\ndocker network create --subnet 172.20.0.0/16 --gateway 172.20.0.1 net","handlingStrategy":"validation","validationCode":"// Verify every gateway is contained in some declared subnet.\nfunc gatewaysHaveSubnets(subnets []string, gateways []net.IP) error {\n    nets := make([]*net.IPNet, 0, len(subnets))\n    for _, s := range subnets {\n        _, ipn, err := net.ParseCIDR(s)\n        if err != nil { return err }\n        nets = append(nets, ipn)\n    }\n    for _, g := range gateways {\n        ok := false\n        for _, ipn := range nets {\n            if ipn.Contains(g) { ok = true; break }\n        }\n        if !ok { return fmt.Errorf(\"no subnet contains gateway %s\", g) }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pair each --gateway with its containing --subnet in configuration templates.","Unit-test IPAM config builders to assert containment.","Use net.IPNet.Contains for programmatic checks before calling the daemon."],"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"}