{"record":{"id":"7859feeb0dc24660","repo":"kubernetes/kops","slug":"cannot-find-subnet-q-declared-in-instance-group","errorCode":null,"errorMessage":"cannot find subnet %q (declared in instance group %q, not found in cluster)","messagePattern":"cannot find subnet %q \\(declared in instance group %q, not found in cluster\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/apis/kops/model/utils.go","lineNumber":42,"sourceCode":")\n\n// FindSubnet returns the subnet with the specified name, or returns nil\nfunc FindSubnet(c *kops.Cluster, subnetName string) *kops.ClusterSubnetSpec {\n\tfor _, subnet := range c.Spec.Networking.Subnets {\n\t\tif subnet.Name == subnetName {\n\t\t\treturn &subnet\n\t\t}\n\t}\n\treturn nil\n}\n\n// FindZonesForInstanceGroup computes the zones for an instance group, which are the zones directly declared in the InstanceGroup, or the subnet zones\nfunc FindZonesForInstanceGroup(c *kops.Cluster, ig *kops.InstanceGroup) ([]string, error) {\n\tzones := sets.NewString(ig.Spec.Zones...)\n\tfor _, subnetName := range ig.Spec.Subnets {\n\t\tsubnet := FindSubnet(c, subnetName)\n\t\tif subnet == nil {\n\t\t\treturn nil, fmt.Errorf(\"cannot find subnet %q (declared in instance group %q, not found in cluster)\", subnetName, ig.ObjectMeta.Name)\n\t\t}\n\n\t\tif subnet.Zone != \"\" {\n\t\t\tzones.Insert(subnet.Zone)\n\t\t}\n\t}\n\treturn zones.List(), nil\n}\n","sourceCodeStart":24,"sourceCodeEnd":51,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/pkg/apis/kops/model/utils.go#L24-L51","documentation":"FindZonesForInstanceGroup resolves the zones for an instance group by combining ig.Spec.Zones with the zones of each subnet named in ig.Spec.Subnets. If a subnet name listed in the instance group does not match any subnet declared in the cluster spec, FindSubnet returns nil and this error is thrown. It is a configuration consistency check: the cluster spec is the source of truth for subnets.","triggerScenarios":"Calling FindZonesForInstanceGroup (directly, or indirectly via Build, DefaultInstanceType, or setupControlPlane) with an ig whose Spec.Subnets contains a name not present in c.Spec.Subnets — e.g. 'utility-us-east-1a' vs 'us-east-1a' mismatch, typo, renamed subnet, or the cluster object passed is not the one the subnets were declared on.","commonSituations":"Hand-edited cluster.yaml where the instance group references a subnet removed or renamed; generating instance groups from a template with hard-coded subnet names; passing a partially-populated Cluster object to the model builder; copying an IG from another cluster whose subnet topology differs.","solutions":["Compare ig.Spec.Subnets entries against c.Spec.Subnets names and correct the subnet name in the instance group spec.","Add the missing subnet to the cluster spec (c.Spec.Subnets) if it was removed or never declared.","Use `kops get ig <name> -o yaml` to inspect the exact subnet names kOps expects, and align the IG with them.","If constructing Cluster/InstanceGroup programmatically, validate subnet names with kops.FindSubnet(c, name) before building."],"exampleFix":"// before (instance group yaml)\nmetadata:\n  name: nodes\nspec:\n  subnets:\n    - utility-us-east-1b   # not declared in cluster spec\n// after\nspec:\n  subnets:\n    - us-east-1b           # matches a subnet in cluster.spec.subnets","handlingStrategy":"validation","validationCode":"func validateIGSubnets(c *kops.Cluster, ig *kops.InstanceGroup) error {\n\tknown := map[string]bool{}\n\tfor _, s := range c.Spec.Subnets {\n\t\tknown[s.Name] = true\n\t}\n\tfor _, n := range ig.Spec.Subnets {\n\t\tif !known[n] {\n\t\t\treturn fmt.Errorf(\"IG %q references undeclared subnet %q\", ig.Name, n)\n\t\t}\n\t}\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":"zones, err := kops.FindZonesForInstanceGroup(cluster, ig)\nif err != nil {\n\tif strings.Contains(err.Error(), \"cannot find subnet\") {\n\t\t// fix IG subnets or cluster spec before retrying\n\t}\n\treturn err\n}","preventionTips":["Always declare subnets in cluster.spec.subnets first, then reference them by exact name in instance groups.","Never hand-edit subnet names; regenerate IGs from the cluster spec.","Run `kops validate cluster` / `kops create -f --dry-run` before applying.","When copying IGs between clusters, re-map subnet names to the target cluster's topology."],"tags":["kops","subnet","instance-group","configuration"],"backgroundTag":"subnet-not-found","analyzedSha":"4c8573c808a73d578c5eadc86d410646ea0b0d73","analyzedAt":"2026-09-05T04:13:19.212Z","contentChangedAt":"2026-09-05T04:13:19.212Z","schemaVersion":2},"datasetVersion":"2026-09-12T07:17:12.445Z"}