k3s-io/k3s · error

Cannot configure unknown flannel backend '%s'

Error message

Cannot configure unknown flannel backend '%s'

What it means

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.

Source

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

			routes = append(routes, "$SUBNET")
		}
		if nm.IPv6Enabled() {
			routes = append(routes, "$IPV6SUBNET")
		}
		if len(routes) == 0 {
			return errors.New("incorrect netMode for flannel tailscale backend")
		}
		advertisedRoutes, err := vpn.GetAdvertisedRoutes()
		if err == nil && advertisedRoutes != nil {
			for _, advertisedRoute := range advertisedRoutes {
				routes = append(routes, advertisedRoute.String())
			}
		}
		backendConf = strings.ReplaceAll(tailscaledBackend, "%Routes%", strings.Join(routes, ","))
	case BackendWireguardNative:
		backendConf = wireguardNativeBackend
	default:
		return fmt.Errorf("Cannot configure unknown flannel backend '%s'", nodeConfig.Flannel.Backend)
	}
	confJSON = strings.ReplaceAll(confJSON, "%backend%", backendConf)

	logrus.Debugf("The flannel configuration is %s", confJSON)
	return agentutil.WriteFile(nodeConfig.Flannel.ConfFile, confJSON)
}

// fundNetMode returns the mode (ipv4, ipv6 or dual-stack) in which flannel is operating
func findNetMode(cidrs []*net.IPNet) (netMode, error) {
	dualStack, err := utilsnet.IsDualStackCIDRs(cidrs)
	if err != nil {
		return 0, err
	}
	if dualStack {
		return ipv4 | ipv6, nil
	}

	for _, cidr := range cidrs {

View on GitHub (pinned to 6ba341e396)

Solutions

1. Use one of the exact values: vxlan, host-gw, wireguard-native, tailscale, none
2. Check the constants in pkg/agent/flannel/flannel.go for the build you are running
3. Trim whitespace and verify casing when generating the flag from templates

Example fix

# before
--flannel-backend wireguard

# after
--flannel-backend wireguard-native

var supportedBackends = map[string]bool{
    "vxlan": true, "host-gw": true, "wireguard-native": true,
    "tailscale": true, "none": true,
}
if !supportedBackends[strings.TrimSpace(backend)] {
    return fmt.Errorf("unknown flannel backend %q", backend)
}

When it happens

Trigger: --flannel-backend with a typo'd or unrecognized value: 'hostgw', 'vxlan ' (trailing space), 'wireguard' (the old name before wireguard-native), 'VXLAN' (case mismatch).

Common situations: 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.

Related errors

• unsupported flannel backend '%s' for Windows
• Flannel configuration not defined
• Failed checking netMode
• Initial server URL host is not defined for load balancer
• --server is required

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