{"record":{"id":"7b997c401dedb032","repo":"k3s-io/k3s","slug":"unsupported-flannel-backend-s-for-windows","errorCode":null,"errorMessage":"unsupported flannel backend '%s' for Windows","messagePattern":"unsupported flannel backend '(.+?)' for Windows","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/agent/flannel/setup.go","lineNumber":224,"sourceCode":"\t\tfor _, cidr := range nodeConfig.AgentConfig.ClusterCIDRs {\n\t\t\tif utilsnet.IsIPv6(cidr.IP) {\n\t\t\t\t// Only one ipv6 range available. This might change in future: https://github.com/kubernetes/enhancements/issues/2593\n\t\t\t\tconfJSON = strings.ReplaceAll(confJSON, \"%CIDR_IPV6%\", cidr.String())\n\t\t\t\tbreak\n\t\t\t}\n\t\t}\n\t} else {\n\t\tconfJSON = strings.ReplaceAll(confJSON, \"%IPV6_ENABLED%\", \"false\")\n\t\tconfJSON = strings.ReplaceAll(confJSON, \"%CIDR_IPV6%\", emptyIPv6Network)\n\t}\n\n\t// precheck and error out unsupported flannel backends for windows.\n\tif goruntime.GOOS == \"windows\" {\n\t\tswitch nodeConfig.Flannel.Backend {\n\t\tcase BackendVXLAN, BackendNone:\n\t\t\t// these are the only supported backends\n\t\tdefault:\n\t\t\treturn fmt.Errorf(\"unsupported flannel backend '%s' for Windows\", nodeConfig.Flannel.Backend)\n\t\t}\n\t}\n\n\tvar backendConf string\n\n\tswitch nodeConfig.Flannel.Backend {\n\tcase BackendVXLAN:\n\t\tbackendConf = vxlanBackend\n\tcase BackendHostGW:\n\t\tbackendConf = hostGWBackend\n\tcase BackendTailscale:\n\t\tvar routes []string\n\t\tif nm.IPv4Enabled() {\n\t\t\troutes = append(routes, \"$SUBNET\")\n\t\t}\n\t\tif nm.IPv6Enabled() {\n\t\t\troutes = append(routes, \"$IPV6SUBNET\")\n\t\t}","sourceCodeStart":206,"sourceCodeEnd":242,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/agent/flannel/setup.go#L206-L242","documentation":"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.","triggerScenarios":"A Windows agent (goruntime.GOOS == 'windows') started where the server flags set --flannel-backend to host-gw, wireguard-native or tailscale.","commonSituations":"Reusing Linux server flags on Windows nodes in mixed-OS clusters; choosing a backend cluster-wide without checking Windows support.","solutions":["Use the default vxlan backend on Windows","Or use 'none' and manage CNI networking yourself","Pick a backend compatible with every OS in the cluster (vxlan is the safe default)"],"exampleFix":"# before (server flags applied to Windows agents)\n--flannel-backend host-gw\n\n# after\n--flannel-backend vxlan","handlingStrategy":"validation","validationCode":"if goruntime.GOOS == \"windows\" {\n    switch backend {\n    case \"vxlan\", \"none\":\n    default:\n        return fmt.Errorf(\"backend %q unsupported on Windows\", backend)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Default to vxlan in mixed-OS clusters","Gate backend flags by OS in your provisioning templates"],"tags":["flannel","windows","backend","config"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}