kubernetes/kops · error

found multiple subnets with name: %q

Error message

found multiple subnets with name: %q

What it means

This error is thrown by NodeupModelContext.FindSubnets (pkg/model/context.go:87) when resolving an InstanceGroup's subnet names to actual cluster Subnet specs. kOps looks up each configured subnet by name in the cluster spec and requires an exact, unique match; more than one Subnet sharing the same name is ambiguous, so the build aborts rather than guessing. It indicates a malformed cluster spec, since kOps normally prevents duplicate subnet names.

Source

Thrown at pkg/model/context.go:87

// 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
}

// FindInstanceGroup returns the instance group with the matching Name (or nil if not found)

View on GitHub (pinned to 4c8573c808)

Solutions

1. Run 'kops get cluster -o yaml' and inspect spec.subnets for two entries with the same name; rename one to a unique name
2. If the duplicate was unintentional, delete the redundant subnet entry with 'kops edit cluster' (or edit the manifest) and keep the one that matches the IG's spec.subnets reference
3. Ensure each instanceGroup's spec.subnets only references names that exist exactly once in the cluster spec
4. Update kOps if a bug in spec migration produced duplicates; re-export the cluster spec

Example fix

// before (cluster spec yaml)
subnets:
- name: us-east-1a
  zone: us-east-1a
  type: Public
- name: us-east-1a
  zone: us-east-1b
  type: Public
// after
subnets:
- name: us-east-1a
  zone: us-east-1a
  type: Public
- name: us-east-1b
  zone: us-east-1b
  type: Public

// Go: before rendering the model, ensure each referenced subnet name is unique
func validateUniqueSubnetNames(cluster *kops.Cluster) error {
	seen := map[string]int{}
	for _, s := range cluster.Spec.Subnets {
		if prev, dup := seen[s.Name]; dup {
			return fmt.Errorf("subnet name %q used at indexes %d and %d", s.Name, prev, dup)
		}
		seen[s.Name] = 1
	}
	return nil
}

func hasUniqueSubnetNames(subnets []kops.ClusterSubnetSpec) bool {
	seen := map[string]bool{}
	for _, s := range subnets {
		if seen[s.Name] { return false }
		seen[s.Name] = true
	}
	return true
}

When it happens

Trigger: Calling FindSubnets with a subnetName that matches more than one entry in b.Cluster.Spec.Subnets — e.g. a hand-edited or merged cluster.yaml where two subnet entries got the same 'name' field, or programmatic spec manipulation that appended duplicate subnet definitions.

Common situations: Manual editing of the cluster spec, YAML merge tooling or 'kops replace' with a spec that duplicated a subnet block, copy-pasting a subnet entry for a second zone without renaming it, or importing/templating cluster configs across environments.

Related errors

• no subnets found in cluster %q
• error populating configuration: %v
• configuration must include Subnets
• error subnets must exist in the cluster
• error instance group cannot span public and private subnets

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