{"record":{"id":"1223b9d4a67a00ee","repo":"k3s-io/k3s","slug":"incorrect-netmode-for-flannel-tailscale-backend","errorCode":null,"errorMessage":"incorrect netMode for flannel tailscale backend","messagePattern":"incorrect netMode for flannel tailscale backend","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/agent/flannel/setup.go","lineNumber":244,"sourceCode":"\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}\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}","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/agent/flannel/setup.go#L226-L262","documentation":"The tailscale flannel backend builds its route advertisement list from the enabled IP families: $SUBNET for IPv4, $IPV6SUBNET for IPv6. If neither family is enabled the routes list is empty and the backend cannot function, so setup fails fast. netMode is derived from cluster-cidr, so this almost always means cluster-cidr contained no usable IPv4 or IPv6 CIDR.","triggerScenarios":"Starting with --flannel-backend=tailscale while --cluster-cidr is empty, contains invalid CIDRs, or none parse as IPv4/IPv6 via utilsnet.IsIPv4CIDR/IsIPv6CIDR.","commonSituations":"Tailscale backend selected on a node where cluster-cidr was not set (e.g. mis-parsed config.yaml), or a custom CIDR string with a typo (e.g. 10.42.0.0/16 dropped mask) that slipped through earlier validation.","solutions":["Set a valid --cluster-cidr with at least one IPv4 or IPv6 CIDR (e.g. --cluster-cidr=10.42.0.0/16) on the server and restart","Check config.yaml on the node for a malformed cluster-cidr entry (missing mask, stray quotes/spaces)","Ensure agents are not overriding cluster-cidr with an empty value"],"exampleFix":"# before\nk3s server --flannel-backend=tailscale --cluster-cidr=\"\" # -> incorrect netMode for flannel tailscale backend\n\n# after\nk3s server --flannel-backend=tailscale --cluster-cidr=10.42.0.0/16,fd01::/48","handlingStrategy":"validation","validationCode":"func hasAnyFamily(cidrs []net.IPNet) bool {\n    for _, c := range cidrs {\n        if utilsnet.IsIPv4CIDR(c) || utilsnet.IsIPv6CIDR(c) { return true }\n    }\n    return false\n}\nif nodeConfig.Flannel.Backend == flannel.BackendTailscale && !hasAnyFamily(nodeConfig.AgentConfig.ClusterCIDRs) {\n    return errors.New(\"tailscale backend requires an IPv4 or IPv6 cluster-cidr\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set an explicit --cluster-cidr when selecting non-default backends","Lint cluster bootstrap manifests for empty/invalid CIDR strings","Parse CIDRs early with netip.ParsePrefix and fail before daemons start"],"tags":["flannel","tailscale","vpn","cluster-cidr","networking"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}