kubernetes/kops · critical

failed to parse subnet CIDR %q: %w

Error message

failed to parse subnet CIDR %q: %w

What it means

On GCE, kOps determines which API server addresses are reachable from nodes by checking each address against the CIDR of every cluster subnet. This error is thrown when a subnet's CIDR string in cluster.spec.networking.subnets cannot be parsed as a valid CIDR prefix by netip.ParsePrefix.

Source

Thrown at pkg/nodemodel/nodeupconfigbuilder.go:419

				// address is unroutable from them even though it is inside the network CIDR. Handing
				// one out only stalls bootstrap on an address that can never answer.
				if cluster.Spec.IsIPv6Only() && !ip.Is6() {
					continue
				}
				if cidr.Contains(ip) || ip.Is6() {
					controlPlaneIPs = append(controlPlaneIPs, additionalIP)
				}
			}
		}

	case kops.CloudProviderGCE:
		// Use the IP address of the internal load balancer (forwarding-rule)
		// Note that on GCE subnets have IP ranges, networks do not
		for _, apiserverIP := range apiserverAddresses {
			for _, subnet := range cluster.Spec.Networking.Subnets {
				cidr, err := netip.ParsePrefix(subnet.CIDR)
				if err != nil {
					return nil, fmt.Errorf("failed to parse subnet CIDR %q: %w", subnet.CIDR, err)
				}
				ip, err := netip.ParseAddr(apiserverIP)
				if err != nil {
					continue
				}
				if cidr.Contains(ip) {
					controlPlaneIPs = append(controlPlaneIPs, apiserverIP)
				}
			}
		}

	case kops.CloudProviderDO, kops.CloudProviderScaleway, kops.CloudProviderAzure, kops.CloudProviderMetal:
		// Use any IP address that is found (including public ones)
		controlPlaneIPs = append(controlPlaneIPs, apiserverAddresses...)
	}

	return controlPlaneIPs, nil
}

View on GitHub (pinned to 4c8573c808)

Solutions

1. Fix the bad subnet entry: `kops edit cluster`, set each subnets[].cidr to a valid prefix (e.g. us-west1 subnet: 10.0.16.0/20), then `kops update cluster`.
2. Read the wrapped netip error and quoted CIDR in the message to identify exactly which subnet entry is malformed.
3. Verify against `gcloud compute networks subnets list` that the CIDRs match the actual GCE subnet ranges.
4. Recreate the cluster spec if the field is empty and let kops/cloud integration populate subnets correctly (delete/re-create subnet entries rather than editing blindly).

Example fix

// before (cluster.yaml)
networking:
  subnets:
  - name: us-west1
    type: Private
    cidr: ""
// after
networking:
  subnets:
  - name: us-west1
    type: Private
    cidr: 10.0.16.0/20

import "net/netip"

func validateSubnetCIDRs(subnets []kops.ClusterSubnetSpec) error {
    for _, subnet := range subnets {
        if _, err := netip.ParsePrefix(subnet.CIDR); err != nil {
            return fmt.Errorf("subnet %q has invalid CIDR %q: %w", subnet.Name, subnet.CIDR, err)
        }
    }
    return nil
}

func hasValidSubnetCIDRs(subnets []kops.ClusterSubnetSpec) bool {
    if len(subnets) == 0 {
        return false
    }
    for _, s := range subnets {
        if _, err := netip.ParsePrefix(s.CIDR); err != nil {
            return false
        }
    }
    return true
}

ips, err := selectControlPlaneIPs(cluster, apiserverAddresses)
if err != nil {
    var perr *net.ParseError
    if errors.As(err, &perr) {
        return fmt.Errorf("GCE subnet spec contains invalid CIDR (fix subnets[].cidr): %w", err)
    }
    return err
}

When it happens

Trigger: Building the nodeup config (BuildConfig) for a GCE cluster where one of cluster.spec.networking.subnets[].cidr is malformed: a bare IP like 10.0.10.0 without /24, an empty string, an IPv6 literal without prefix length, or a region/name mistakenly placed in the cidr field.

Common situations: Hand-edited cluster manifest for GCE where subnet.cidr was omitted or set to the subnet name instead of a range; IPv6 subnets filled in with a bare address; tooling/terraform exporting subnet fields into the wrong key; copy-pasting an AWS-style subnet spec into a GCE cluster.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to parse network CIDR %q: %w
• cannot parse network name %q as either project/network or ne
• subnet %q has unknown type %q
• unable to parse CIDR for %q: %v
• unable to calculate CIDR mask size for %q: %q

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