kubernetes/kops · error

subnet not found: %q

Error message

subnet not found: %q

What it means

NodeupModelContext looks up a subnet by name among the cluster's spec.networking.subnets. If no subnet in the cluster spec matches the requested subnetName, it returns this error; the caller cannot build node/instance-group configuration without a valid subnet reference. A similar sibling error fires when more than one subnet shares the name.

Source

Thrown at pkg/model/context.go:84

	// AdditionalObjects holds cluster-asssociated configuration objects, other than the Cluster and InstanceGroups.
	AdditionalObjects kubemanifest.ObjectList
}

// GatherSubnets maps the subnet names in an InstanceGroup to the ClusterSubnetSpec objects (which are stored on the Cluster)
func (b *KopsModelContext) GatherSubnets(ig *kops.InstanceGroup) ([]*kops.ClusterSubnetSpec, error) {
	var subnets []*kops.ClusterSubnetSpec
	var subnetType kops.SubnetType

	for _, subnetName := range ig.Spec.Subnets {
		var matches []*kops.ClusterSubnetSpec
		for i := range b.Cluster.Spec.Networking.Subnets {
			clusterSubnet := &b.Cluster.Spec.Networking.Subnets[i]
			if clusterSubnet.Name == subnetName {
				matches = append(matches, clusterSubnet)
			}
		}
		if len(matches) == 0 {
			return nil, fmt.Errorf("subnet not found: %q", subnetName)
		}
		if len(matches) > 1 {
			return nil, fmt.Errorf("found multiple subnets with name: %q", subnetName)
		}
		subnets = append(subnets, matches[0])

		// @step: check the instance is not cross subnet types
		switch subnetType {
		case "":
			subnetType = matches[0].Type
		default:
			if matches[0].Type != subnetType {
				return nil, fmt.Errorf("found subnets of different types: %v", strings.Join([]string{string(subnetType), string(matches[0].Type)}, ","))
			}
		}
	}

	return subnets, nil

View on GitHub (pinned to 4c8573c808)

Solutions

1. List subnets with `kops get cluster -o yaml` and compare against the subnet name referenced by your instance group.
2. Fix the typo or update the instance group: `kops edit ig <name>` and set subnets to an existing subnet name.
3. If the subnet was removed, re-add it to spec.networking.subnets or delete/recreate the instance group in a valid subnet.
4. Ensure the referenced subnet name is unique in the spec (duplicate names trigger the 'found multiple subnets' error).

Example fix

// before (instance group yaml)
subnets: ["us-east-1b"]   # cluster only defines subnet "us-east-1a"
// after
subnets: ["us-east-1a"]

func subnetExists(cluster *kops.Cluster, name string) bool {
    for _, s := range cluster.Spec.Networking.Subnets {
        if s.Name == name { return true }
    }
    return false
}
// call before applying instance groups referencing subnets

func findSubnet(cluster *kops.Cluster, name string) *kops.ClusterSubnetSpec {
    for i := range cluster.Spec.Networking.Subnets {
        if cluster.Spec.Networking.Subnets[i].Name == name {
            return &cluster.Spec.Networking.Subnets[i]
        }
    }
    return nil
}

subnets, err := modelContext.FindSubnets(c, nodeupConfig)
if err != nil && strings.Contains(err.Error(), "subnet not found") {
    return fmt.Errorf("instance group references missing subnet; run `kops get ig` and fix subnets: %w", err)
}

When it happens

Trigger: Referencing a subnet name in an instance group (or topology/utility subnet lookup) that does not exist in cluster.spec.networking.subnets — typically a typo, a deleted subnet, or using a subnet from another cluster/zone.

Common situations: Renaming or deleting subnets in the cluster spec while instance groups still reference the old name; typos in `instancegroup.spec.subnets`; splitting a cluster across regions with mismatched subnet lists.

Related errors

• cannot find subnet %q (declared in instance group %q, not fo
• subnet %q had unknown type %q
• subnet %q must specify a zone or the ID of an existing subne
• could not determine cluster region: no subnet specifies a zo
• error retrieving subnet with id %s: %v

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