dual-stack or IPv6 are not supported on Windows node

Error message

dual-stack or IPv6 are not supported on Windows node

What it means

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.

Source

Thrown at pkg/agent/run.go:95

	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")
	}
	// The net/bridge/bridge-nf-call-{ip,ip6}tables sysctls are only required by kube-proxy
	// and flannel. When both are disabled the node is using an alternative CNI, so leave
	// these sysctls untouched for the administrator to manage. See
	// https://github.com/k3s-io/k3s/issues/14022. The flannel backend is compared against the
	// "none" literal rather than flannel.BackendNone to avoid importing the flannel package,
	// which registers all flannel backends via init().
	setBridgeFilter := !config.KubeProxyDisabled(ctx, nodeConfig, proxy) || nodeConfig.Flannel.Backend != "none"
	syssetup.Configure(enableIPv6, setBridgeFilter, conntrackConfig)
	nodeConfig.AgentConfig.EnableIPv4 = enableIPv4
	nodeConfig.AgentConfig.EnableIPv6 = enableIPv6

	if err := executor.Bootstrap(ctx, nodeConfig, cfg); err != nil {

View on GitHub (pinned to 6ba341e396)

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

Example fix

# before (server)
k3s server --cluster-cidr=10.42.0.0/16,fd01::/48 ...
k3s.exe agent ... # Windows -> dual-stack or IPv6 are not supported on Windows node

# after (IPv4-only cluster for mixed OS)
k3s server --cluster-cidr=10.42.0.0/16 ...

Defensive patterns

Strategy: validation

Validate before calling

func windowsCompatible(cidrs []net.IPNet) error {
    if goruntime.GOOS != "windows" { return nil }
    for _, c := range cidrs {
        if utilsnet.IsIPv6CIDR(c) { return errors.New("Windows agents require an IPv4-only cluster-cidr") }
    }
    return nil
}

Prevention

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

When it happens

Trigger: 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).

Common situations: 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.

Related errors

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