{"record":{"id":"8ca0a7f19895166d","repo":"k3s-io/k3s","slug":"cannot-configure-unknown-flannel-backend-s","errorCode":null,"errorMessage":"Cannot configure unknown flannel backend '%s'","messagePattern":"Cannot configure unknown flannel backend '(.+?)'","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/agent/flannel/setup.go","lineNumber":256,"sourceCode":"\t\t\troutes = append(routes, \"$SUBNET\")\n\t\t}\n\t\tif nm.IPv6Enabled() {\n\t\t\troutes = append(routes, \"$IPV6SUBNET\")\n\t\t}\n\t\tif len(routes) == 0 {\n\t\t\treturn errors.New(\"incorrect netMode for flannel tailscale backend\")\n\t\t}\n\t\tadvertisedRoutes, err := vpn.GetAdvertisedRoutes()\n\t\tif err == nil && advertisedRoutes != nil {\n\t\t\tfor _, advertisedRoute := range advertisedRoutes {\n\t\t\t\troutes = append(routes, advertisedRoute.String())\n\t\t\t}\n\t\t}\n\t\tbackendConf = strings.ReplaceAll(tailscaledBackend, \"%Routes%\", strings.Join(routes, \",\"))\n\tcase BackendWireguardNative:\n\t\tbackendConf = wireguardNativeBackend\n\tdefault:\n\t\treturn fmt.Errorf(\"Cannot configure unknown flannel backend '%s'\", nodeConfig.Flannel.Backend)\n\t}\n\tconfJSON = strings.ReplaceAll(confJSON, \"%backend%\", backendConf)\n\n\tlogrus.Debugf(\"The flannel configuration is %s\", confJSON)\n\treturn agentutil.WriteFile(nodeConfig.Flannel.ConfFile, confJSON)\n}\n\n// fundNetMode returns the mode (ipv4, ipv6 or dual-stack) in which flannel is operating\nfunc findNetMode(cidrs []*net.IPNet) (netMode, error) {\n\tdualStack, err := utilsnet.IsDualStackCIDRs(cidrs)\n\tif err != nil {\n\t\treturn 0, err\n\t}\n\tif dualStack {\n\t\treturn ipv4 | ipv6, nil\n\t}\n\n\tfor _, cidr := range cidrs {","sourceCodeStart":238,"sourceCodeEnd":274,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/agent/flannel/setup.go#L238-L274","documentation":"The backend-to-JSON switch in setup.go recognizes exactly the constants BackendVXLAN ('vxlan'), BackendHostGW ('host-gw'), BackendTailscale ('tailscale') and BackendWireguardNative ('wireguard-native'); 'none' is handled earlier. The default branch rejects every other string. Comparison is exact — case and whitespace sensitive.","triggerScenarios":"--flannel-backend with a typo'd or unrecognized value: 'hostgw', 'vxlan ' (trailing space), 'wireguard' (the old name before wireguard-native), 'VXLAN' (case mismatch).","commonSituations":"Typos in flags or templated config; version skew where a backend was renamed or does not exist in this build; whitespace injected by config templating.","solutions":["Use one of the exact values: vxlan, host-gw, wireguard-native, tailscale, none","Check the constants in pkg/agent/flannel/flannel.go for the build you are running","Trim whitespace and verify casing when generating the flag from templates"],"exampleFix":"# before\n--flannel-backend wireguard\n\n# after\n--flannel-backend wireguard-native","handlingStrategy":"validation","validationCode":"var supportedBackends = map[string]bool{\n    \"vxlan\": true, \"host-gw\": true, \"wireguard-native\": true,\n    \"tailscale\": true, \"none\": true,\n}\nif !supportedBackends[strings.TrimSpace(backend)] {\n    return fmt.Errorf(\"unknown flannel backend %q\", backend)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate backend names against the constants in pkg/agent/flannel/flannel.go for your build","Trim whitespace and match case exactly when templating flags","Watch for renames across versions (e.g. wireguard -> wireguard-native)"],"tags":["flannel","config","backend","validation"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}