{"record":{"id":"3390fbd70eb7c5f8","repo":"k3s-io/k3s","slug":"dual-stack-or-ipv6-are-not-supported-on-windows-no","errorCode":null,"errorMessage":"dual-stack or IPv6 are not supported on Windows node","messagePattern":"dual-stack or IPv6 are not supported on Windows node","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/agent/run.go","lineNumber":95,"sourceCode":"\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\")\n\t}\n\t// The net/bridge/bridge-nf-call-{ip,ip6}tables sysctls are only required by kube-proxy\n\t// and flannel. When both are disabled the node is using an alternative CNI, so leave\n\t// these sysctls untouched for the administrator to manage. See\n\t// https://github.com/k3s-io/k3s/issues/14022. The flannel backend is compared against the\n\t// \"none\" literal rather than flannel.BackendNone to avoid importing the flannel package,\n\t// which registers all flannel backends via init().\n\tsetBridgeFilter := !config.KubeProxyDisabled(ctx, nodeConfig, proxy) || nodeConfig.Flannel.Backend != \"none\"\n\tsyssetup.Configure(enableIPv6, setBridgeFilter, conntrackConfig)\n\tnodeConfig.AgentConfig.EnableIPv4 = enableIPv4\n\tnodeConfig.AgentConfig.EnableIPv6 = enableIPv6\n\n\tif err := executor.Bootstrap(ctx, nodeConfig, cfg); err != nil {","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/agent/run.go#L77-L113","documentation":"During agent startup k3s computes enableIPv6 from the cluster CIDRs (IPv6-only or dual-stack both set it). On Windows nodes IPv6/dual-stack pod networking is not implemented, so startup aborts with this error before any daemon is configured. It is a platform capability gate, not a transient failure.","triggerScenarios":"Joining a Windows agent (k3s.exe agent) to a cluster whose --cluster-cidr contains an IPv6 CIDR, whether IPv6-only or dual-stack (IPv4+IPv6).","commonSituations":"Mixed OS clusters where the server was rolled out dual-stack before Windows support was considered; enforcing IPv6 corporate addressing then adding Windows worker nodes.","solutions":["Run Windows agents against an IPv4-only cluster (cluster-cidr with only IPv4 CIDRs) — recreate/repair the cluster accordingly","Use Linux nodes for any IPv6 or dual-stack workloads","Track upstream k3s Windows IPv6 support before re-introducing IPv6 CIDRs"],"exampleFix":"# before (server)\nk3s server --cluster-cidr=10.42.0.0/16,fd01::/48 ...\nk3s.exe agent ... # Windows -> dual-stack or IPv6 are not supported on Windows node\n\n# after (IPv4-only cluster for mixed OS)\nk3s server --cluster-cidr=10.42.0.0/16 ...","handlingStrategy":"validation","validationCode":"func windowsCompatible(cidrs []net.IPNet) error {\n    if goruntime.GOOS != \"windows\" { return nil }\n    for _, c := range cidrs {\n        if utilsnet.IsIPv6CIDR(c) { return errors.New(\"Windows agents require an IPv4-only cluster-cidr\") }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Decide IP family strategy before adding Windows nodes; keep mixed-OS clusters IPv4-only","Gate cluster creation pipelines: reject IPv6 CIDRs when windows agents are planned","Track k3s release notes for Windows dual-stack support changes"],"tags":["windows","ipv6","dual-stack","platform","cluster-cidr"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}