k3s-io/k3s · error

unsupported flannel backend

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.

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
• failed to determine MTU for
• Flannel configuration not defined
• VPN Error. Tailscale requires a JoinKey
• cluster-cidr: and service-cidr: , must share the same IP…

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

Appendix: 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)