cluster-cidr: %v and service-cidr: %v, must share the same I

Error message

cluster-cidr: %v and service-cidr: %v, must share the same IP version (IPv4, IPv6 or dual-stack)

What it means

During agent startup validation, IP family booleans (serviceIPv4/clusterIPv4/serviceIPv6/clusterIPv6, plus dual-stack flags) are computed from AgentConfig.ServiceCIDR(s) and ClusterCIDR(s); any disagreement between the two sides aborts with this error echoing both CIDR lists. The ranges must both be IPv4, both IPv6, or both dual-stack (one v4 + one v6 each).

Source

Thrown at pkg/agent/run.go:82

	}
	dualService, err := utilsnet.IsDualStackCIDRs(nodeConfig.AgentConfig.ServiceCIDRs)
	if err != nil {
		return errors.WithMessage(err, "failed to validate service-cidr")
	}
	dualNode, err := utilsnet.IsDualStackIPs(nodeConfig.AgentConfig.NodeIPs)
	if err != nil {
		return errors.WithMessage(err, "failed to validate node-ip")
	}
	serviceIPv4 := utilsnet.IsIPv4CIDR(nodeConfig.AgentConfig.ServiceCIDR)
	clusterIPv4 := utilsnet.IsIPv4CIDR(nodeConfig.AgentConfig.ClusterCIDR)
	nodeIPv4 := utilsnet.IsIPv4String(nodeConfig.AgentConfig.NodeIP)
	serviceIPv6 := utilsnet.IsIPv6CIDR(nodeConfig.AgentConfig.ServiceCIDR)
	clusterIPv6 := utilsnet.IsIPv6CIDR(nodeConfig.AgentConfig.ClusterCIDR)
	nodeIPv6 := utilsnet.IsIPv6String(nodeConfig.AgentConfig.NodeIP)

	// check that cluster-cidr and service-cidr have the same IP versions
	if (serviceIPv6 != clusterIPv6) || (dualCluster != dualService) || (serviceIPv4 != clusterIPv4) {
		return fmt.Errorf("cluster-cidr: %v and service-cidr: %v, must share the same IP version (IPv4, IPv6 or dual-stack)", nodeConfig.AgentConfig.ClusterCIDRs, nodeConfig.AgentConfig.ServiceCIDRs)
	}

	// check that node-ip has the IP versions set in cluster-cidr
	if (clusterIPv6 && !(nodeIPv6 || dualNode)) || (dualCluster && !dualNode) || (clusterIPv4 && !(nodeIPv4 || dualNode)) {
		return fmt.Errorf("cluster-cidr: %v and node-ip: %v, must share the same IP version (IPv4, IPv6 or dual-stack)", nodeConfig.AgentConfig.ClusterCIDRs, nodeConfig.AgentConfig.NodeIPs)
	}

	enableIPv6 := dualCluster || clusterIPv6
	enableIPv4 := dualCluster || clusterIPv4

	// dualStack or IPv6 are not supported on Windows node
	if (goruntime.GOOS == "windows") && enableIPv6 {
		return errors.New("dual-stack or IPv6 are not supported on Windows node")
	}

	conntrackConfig, err := getConntrackConfig(nodeConfig)
	if err != nil {
		return errors.WithMessage(err, "failed to validate kube-proxy conntrack configuration")

View on GitHub (pinned to 6ba341e396)

Solutions

Make the families symmetric: both single-stack IPv4, both IPv6, or both exactly one v4 + one v6 CIDR
Set the flags on the server (it hands them to agents) and restart, e.g. --cluster-cidr=10.42.0.0/16,fd01::/48 --service-cidr=10.43.0.0/16,fd02::/108
Remove stray CIDRs; the error message prints both lists — use it to see what the agent actually received

Example fix

# before
--cluster-cidr=10.42.0.0/16,fd01::/48 --service-cidr=10.43.0.0/16

# after
--cluster-cidr=10.42.0.0/16,fd01::/48 --service-cidr=10.43.0.0/16,fd02::/108

Defensive patterns

Strategy: validation

Validate before calling

func familyOf(cidrs []*net.IPNet) (v4, v6 bool) {
    for _, c := range cidrs {
        if utilsnet.IsIPv6CIDR(c) {
            v6 = true
        } else {
            v4 = true
        }
    }
    return
}
sv4, sv6 := familyOf(serviceCIDRs)
cv4, cv6 := familyOf(clusterCIDRs)
if sv4 != cv4 || sv6 != cv6 {
    return errors.New("cluster-cidr and service-cidr must share the same IP family composition")
}

Prevention

Always change --cluster-cidr and --service-cidr together, keeping family composition identical
For dual-stack, give each side exactly one IPv4 and one IPv6 CIDR
Validate both flag sets in CI/pre-flight before restarting servers and agents

When it happens

Trigger: --cluster-cidr=10.42.0.0/16 with --service-cidr=fd00::/108; cluster-cidr dual-stack (10.42.0.0/16,fd01::/48) while service-cidr is single-stack 10.43.0.0/16 (or vice versa).

Common situations: Half-finished dual-stack migration; leftover IPv6 service range after dropping the IPv6 pod range; editing one flag but not the other; server and agent flag drift.

Related errors

AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15). Data as JSON: /api/errors/4d16c620f19e33fc. Report an issue: GitHub.