{"record":{"id":"a0e2a8a94d14efd5","repo":"docker/cli","slug":"no-matching-subnet-for-aux-address-s","errorCode":null,"errorMessage":"no matching subnet for aux-address %s","messagePattern":"no matching subnet for aux-address (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/network/create.go","lineNumber":238,"sourceCode":"\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}\n\t\t\tif !ok {\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tiData[s].AuxAddress[name] = auxAddr\n\t\t\tmatch = true\n\t\t}\n\t\tif !match {\n\t\t\treturn nil, fmt.Errorf(\"no matching subnet for aux-address %s\", aa)\n\t\t}\n\t}\n\n\tidl := make([]network.IPAMConfig, 0, len(iData))\n\tfor _, v := range iData {\n\t\tidl = append(idl, *v)\n\t}\n\n\treturn &network.IPAM{\n\t\tDriver:  options.driver,\n\t\tConfig:  idl,\n\t\tOptions: options.driverOpts.GetAll(),\n\t}, nil\n}\n\nfunc subnetMatches(subnet, data string) (bool, error) {\n\tvar ip net.IP\n","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/network/create.go#L220-L256","documentation":"Returned by createIPAMConfig when an --aux-address value does not lie within any configured --subnet. Like gateways, aux-addresses are matched against subnets by containment (create.go:217-239); an aux address that matches no subnet produces this error so the daemon never receives an auxiliary address outside its managed ranges.","triggerScenarios":"Passing `--aux-address name=IP` where IP is not contained by any --subnet. Example: `docker network create --subnet 172.20.0.0/16 --aux-address dns=10.0.0.9 net`. Also triggered when an aux-address is given with no --subnet at all.","commonSituations":"Network driver expecting aux addresses (e.g. overlay/macvlan) but the operator reuses IPs from a different network, or a subnet was changed and the aux addresses were not updated to match.","solutions":["Confirm each --aux-address IP belongs to one of the declared --subnet CIDRs.","Add or correct the --subnet so it covers the auxiliary address.","Remove stale --aux-address entries inherited from another network's template."],"exampleFix":"// before\ndocker network create --subnet 172.20.0.0/16 --aux-address dns=10.0.0.9 net\n// after\ndocker network create --subnet 172.20.0.0/16 --aux-address dns=172.20.0.9 net","handlingStrategy":"validation","validationCode":"// Check each aux-address IP is within a declared subnet.\nfunc auxAddressesHaveSubnets(subnets []string, aux map[string]string) 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 name, ip := range aux {\n        parsed := net.ParseIP(ip)\n        if parsed == nil { return fmt.Errorf(\"bad aux ip %s\", ip) }\n        ok := false\n        for _, ipn := range nets { if ipn.Contains(parsed) { ok = true; break } }\n        if !ok { return fmt.Errorf(\"no subnet for aux-address %s (%s)\", name, ip) }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep aux-address and subnet declarations co-located in config.","Regenerate aux addresses whenever a subnet CIDR changes.","Validate containment in config-rendering code before deployment."],"tags":["network","ipam","aux-address","docker-cli"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}