{"record":{"id":"4d16c620f19e33fc","repo":"k3s-io/k3s","slug":"cluster-cidr-v-and-service-cidr-v-must-share","errorCode":null,"errorMessage":"cluster-cidr: %v and service-cidr: %v, must share the same IP version (IPv4, IPv6 or dual-stack)","messagePattern":"cluster-cidr: (.+?) and service-cidr: (.+?), must share the same IP version \\(IPv4, IPv6 or dual-stack\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/agent/run.go","lineNumber":82,"sourceCode":"\t}\n\tdualService, err := utilsnet.IsDualStackCIDRs(nodeConfig.AgentConfig.ServiceCIDRs)\n\tif err != nil {\n\t\treturn errors.WithMessage(err, \"failed to validate service-cidr\")\n\t}\n\tdualNode, err := utilsnet.IsDualStackIPs(nodeConfig.AgentConfig.NodeIPs)\n\tif err != nil {\n\t\treturn errors.WithMessage(err, \"failed to validate node-ip\")\n\t}\n\tserviceIPv4 := utilsnet.IsIPv4CIDR(nodeConfig.AgentConfig.ServiceCIDR)\n\tclusterIPv4 := utilsnet.IsIPv4CIDR(nodeConfig.AgentConfig.ClusterCIDR)\n\tnodeIPv4 := utilsnet.IsIPv4String(nodeConfig.AgentConfig.NodeIP)\n\tserviceIPv6 := utilsnet.IsIPv6CIDR(nodeConfig.AgentConfig.ServiceCIDR)\n\tclusterIPv6 := utilsnet.IsIPv6CIDR(nodeConfig.AgentConfig.ClusterCIDR)\n\tnodeIPv6 := utilsnet.IsIPv6String(nodeConfig.AgentConfig.NodeIP)\n\n\t// check that cluster-cidr and service-cidr have the same IP versions\n\tif (serviceIPv6 != clusterIPv6) || (dualCluster != dualService) || (serviceIPv4 != clusterIPv4) {\n\t\treturn 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)\n\t}\n\n\t// check that node-ip has the IP versions set in cluster-cidr\n\tif (clusterIPv6 && !(nodeIPv6 || dualNode)) || (dualCluster && !dualNode) || (clusterIPv4 && !(nodeIPv4 || dualNode)) {\n\t\treturn 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)\n\t}\n\n\tenableIPv6 := dualCluster || clusterIPv6\n\tenableIPv4 := dualCluster || clusterIPv4\n\n\t// dualStack or IPv6 are not supported on Windows node\n\tif (goruntime.GOOS == \"windows\") && enableIPv6 {\n\t\treturn errors.New(\"dual-stack or IPv6 are not supported on Windows node\")\n\t}\n\n\tconntrackConfig, err := getConntrackConfig(nodeConfig)\n\tif err != nil {\n\t\treturn errors.WithMessage(err, \"failed to validate kube-proxy conntrack configuration\")","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/agent/run.go#L64-L100","documentation":"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).","triggerScenarios":"--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).","commonSituations":"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.","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"],"exampleFix":"# before\n--cluster-cidr=10.42.0.0/16,fd01::/48 --service-cidr=10.43.0.0/16\n\n# after\n--cluster-cidr=10.42.0.0/16,fd01::/48 --service-cidr=10.43.0.0/16,fd02::/108","handlingStrategy":"validation","validationCode":"func familyOf(cidrs []*net.IPNet) (v4, v6 bool) {\n    for _, c := range cidrs {\n        if utilsnet.IsIPv6CIDR(c) {\n            v6 = true\n        } else {\n            v4 = true\n        }\n    }\n    return\n}\nsv4, sv6 := familyOf(serviceCIDRs)\ncv4, cv6 := familyOf(clusterCIDRs)\nif sv4 != cv4 || sv6 != cv6 {\n    return errors.New(\"cluster-cidr and service-cidr must share the same IP family composition\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["network","dual-stack","ipv6","config","agent","cidr"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}