kubernetes/kops · error

error subnets must exist in the cluster

Error message

error subnets must exist in the cluster

What it means

This error comes from `kops toolbox instance-selector` when validating user-provided subnets via validateUserSubnetsWithClusterSubnets. Every subnet passed by --subnets (or the instance-selector flags) is checked against the subnets actually defined in the cluster spec (ClusterSpec.Subnets); if even one user subnet name has no matching cluster subnet Name, validation fails and this error is returned. It exists to catch typos and out-of-cluster subnets before an instance group referencing them is created.

Source

Thrown at cmd/kops/toolbox_instance-selector.go:473

	err = validateAllPrivateOrPublicSubnets(userSubnets)
	if err != nil {
		return err
	}
	return nil
}

// validateUserSubnetsWithClusterSubnets makes sure the userSubnets are part of the cluster subnets
func validateUserSubnetsWithClusterSubnets(userSubnets []string, clusterSubnets []kops.ClusterSubnetSpec) error {
	for _, userSubnet := range userSubnets {
		userSubnetValid := false
		for _, clusterSubnet := range clusterSubnets {
			if clusterSubnet.Name == userSubnet {
				userSubnetValid = true
				break
			}
		}
		if !userSubnetValid {
			return fmt.Errorf("error subnets must exist in the cluster")
		}
	}
	return nil
}

// validateAllPrivateOrPublicSubnets makes sure the passed in subnets are all utility (public) subnets or private subnets
func validateAllPrivateOrPublicSubnets(userSubnets []string) error {
	utilitySubnets := 0
	for _, userSubnet := range userSubnets {
		if strings.HasPrefix(userSubnet, "utility-") {
			utilitySubnets++
		}
	}

	if utilitySubnets != 0 && len(userSubnets) != utilitySubnets {
		return fmt.Errorf("error instance group cannot span public and private subnets")
	}
	return nil

View on GitHub (pinned to 4c8573c808)

Solutions

1. Run `kops get cluster <name> -o yaml` and check spec.subnets names; use exactly those names in --subnets
2. Fix any typos in the --subnets flag values (names are matched exactly, case-sensitive)
3. Verify you are targeting the intended cluster with --cluster-name; wrong cluster means wrong subnet list
4. If a subnet is genuinely missing, add it to the cluster spec (kops edit cluster) and update the cloud before creating the instance group
5. Use the logical kOps name (e.g. utility-us-east-1a), not the EC2 subnet-ID

Example fix

// before
kops toolbox instance-selector --cluster-name prod.example.com --subnets subnet-0abc123def456 --name nodes

// after
kops toolbox instance-selector --cluster-name prod.example.com --subnets us-east-1a --name nodes

cluster, err := kopsclientset.GetCluster(clusterName)
if err != nil { return err }
clusterSubnetNames := sets.NewString()
for _, s := range cluster.Spec.Subnets { clusterSubnetNames.Insert(s.Name) }
for _, u := range requestedSubnets {
    if !clusterSubnetNames.Has(u) {
        return fmt.Errorf("subnet %q not found in cluster %q; valid: %v", u, clusterName, clusterSubnetNames.List())
    }
}

When it happens

Trigger: Running `kops toolbox instance-selector` with a --subnets value (e.g. "us-east-1a" or "utility-us-east-1a") that does not match any subnet Name in the target cluster's ClusterSubnetSpec list. Also happens when the wrong cluster name is given, so validation runs against a cluster whose subnet list doesn't include the requested subnets.

Common situations: Typo in subnet name; using an AWS subnet ID (subnet-xxxx) instead of the logical subnet name kOps uses; copy-pasting subnets from a different cluster; cluster spec changed and a subnet was renamed/removed while scripts still reference the old name; running against a dev cluster config while reusing prod subnet names.

Related errors

• spec.PublicKey is required
• adding keypair to %q is not supported
• unable to parse YAML %v: %v
• error adding SSH public key: %v
• parsing file %q: %v

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/9fdf1052031458d4. Report an issue: GitHub.