k3s-io/k3s · error

unsupported flannel backend '%s' for Windows

Error message

unsupported flannel backend '%s' for Windows

What it means

setup.go prechecks the flannel backend on Windows nodes: only BackendVXLAN ('vxlan') and BackendNone ('none') are allowed (pkg/agent/flannel/flannel.go constants). Any other backend value returns this error before the flannel config JSON is written, because the other data paths are not implemented on Windows.

Source

Thrown at pkg/agent/flannel/setup.go:224

		for _, cidr := range nodeConfig.AgentConfig.ClusterCIDRs {
			if utilsnet.IsIPv6(cidr.IP) {
				// Only one ipv6 range available. This might change in future: https://github.com/kubernetes/enhancements/issues/2593
				confJSON = strings.ReplaceAll(confJSON, "%CIDR_IPV6%", cidr.String())
				break
			}
		}
	} else {
		confJSON = strings.ReplaceAll(confJSON, "%IPV6_ENABLED%", "false")
		confJSON = strings.ReplaceAll(confJSON, "%CIDR_IPV6%", emptyIPv6Network)
	}

	// precheck and error out unsupported flannel backends for windows.
	if goruntime.GOOS == "windows" {
		switch nodeConfig.Flannel.Backend {
		case BackendVXLAN, BackendNone:
			// these are the only supported backends
		default:
			return fmt.Errorf("unsupported flannel backend '%s' for Windows", nodeConfig.Flannel.Backend)
		}
	}

	var backendConf string

	switch nodeConfig.Flannel.Backend {
	case BackendVXLAN:
		backendConf = vxlanBackend
	case BackendHostGW:
		backendConf = hostGWBackend
	case BackendTailscale:
		var routes []string
		if nm.IPv4Enabled() {
			routes = append(routes, "$SUBNET")
		}
		if nm.IPv6Enabled() {
			routes = append(routes, "$IPV6SUBNET")
		}

View on GitHub (pinned to 6ba341e396)

Solutions

1. Use the default vxlan backend on Windows
2. Or use 'none' and manage CNI networking yourself
3. Pick a backend compatible with every OS in the cluster (vxlan is the safe default)

Example fix

# before (server flags applied to Windows agents)
--flannel-backend host-gw

# after
--flannel-backend vxlan

if goruntime.GOOS == "windows" {
    switch backend {
    case "vxlan", "none":
    default:
        return fmt.Errorf("backend %q unsupported on Windows", backend)
    }
}

When it happens

Trigger: A Windows agent (goruntime.GOOS == 'windows') started where the server flags set --flannel-backend to host-gw, wireguard-native or tailscale.

Common situations: Reusing Linux server flags on Windows nodes in mixed-OS clusters; choosing a backend cluster-wide without checking Windows support.

Related errors

• Cannot configure unknown flannel backend '%s'
• Flannel configuration not defined
• VPN Error. Tailscale requires a JoinKey
• failed to determine MTU for %s interface
• insufficient PSK bytes

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