ipv4 mode requested but no ipv4 network provided

Error message

ipv4 mode requested but no ipv4 network provided

What it means

Thrown by flannel startup after the network backend is registered: the derived netMode says IPv4 is enabled (cluster-cidr contains an IPv4 CIDR) but the flannel subnet-manager config.Network (the IPv4 pod network) is empty. In k3s the flannel conf's Network field is populated from the IPv4 cluster CIDR, so this error signals an inconsistency between the cluster's declared IP families and what flannel was actually configured with.

Source

Thrown at pkg/agent/flannel/flannel.go:99

	bm := backend.NewManager(ctx, sm, extIface)

	be, err := bm.GetBackend(config.BackendType)
	if err != nil {
		return errors.WithMessage(err, "failed to create the flannel backend")
	}

	bn, err := be.RegisterNetwork(ctx, wg, config)
	if err != nil {
		return errors.WithMessage(err, "failed to register flannel network")
	}
	trafficMngr := &iptables.IPTablesManager{}
	err = trafficMngr.Init(ctx)
	if err != nil {
		return errors.WithMessage(err, "failed to initialize flannel ipTables manager")
	}

	if nm.IPv4Enabled() && config.Network.Empty() {
		return errors.New("ipv4 mode requested but no ipv4 network provided")
	}

	// setup masq rules
	prevNetwork := ReadCIDRFromSubnetFile(subnetFile, "FLANNEL_NETWORK")
	prevSubnet := ReadCIDRFromSubnetFile(subnetFile, "FLANNEL_SUBNET")

	prevIPv6Network := ReadIP6CIDRFromSubnetFile(subnetFile, "FLANNEL_IPV6_NETWORK")
	prevIPv6Subnet := ReadIP6CIDRFromSubnetFile(subnetFile, "FLANNEL_IPV6_SUBNET")
	if flannelIPv6Masq {
		err = trafficMngr.SetupAndEnsureMasqRules(ctx, config.Network, prevSubnet, prevNetwork, config.IPv6Network, prevIPv6Subnet, prevIPv6Network, bn.Lease(), 60, false)
	} else {
		// set empty flannel ipv6 Network to prevent masquerading
		err = trafficMngr.SetupAndEnsureMasqRules(ctx, config.Network, prevSubnet, prevNetwork, ip.IP6Net{}, prevIPv6Subnet, prevIPv6Network, bn.Lease(), 60, false)
	}
	if err != nil {
		return errors.WithMessage(err, "failed to setup masq rules")
	}

View on GitHub (pinned to 6ba341e396)

Solutions

Ensure --cluster-cidr contains a valid IPv4 CIDR on server and agents when the cluster is IPv4/dual-stack
If using a custom flannel conf (--flannel-conf / Flannel.ConfOverride), include a valid IPv4 "Network" field or switch the cluster to IPv6-only
Align agent and server cluster-cidr values (agents inherit from the cluster; do not override them to a different family)
Recreate the flannel state directory/subnet files if they were left stale after a CIDR change

Example fix

// custom flannel conf
// before
{ "EnableIPv4": true, "Backend": { "Type": "vxlan" } } // no Network -> ipv4 mode requested but no ipv4 network provided

// after
{ "EnableIPv4": true, "Network": "10.42.0.0/16", "Backend": { "Type": "vxlan" } }

Defensive patterns

Strategy: validation

Validate before calling

nm, err := findNetMode(nodeConfig.AgentConfig.ClusterCIDRs)
if err != nil { return err }
if nm.IPv4Enabled() && config.Network.Empty() {
    return fmt.Errorf("refusing to start flannel: IPv4 enabled by cluster-cidr %v but flannel Network is empty", nodeConfig.AgentConfig.ClusterCIDRs)
}

Try / catch

if err := flannel(ctx, wg, ...); err != nil {
    if errors.Is(err, errIPv4NoNetwork) || strings.Contains(err.Error(), "no ipv4 network provided") {
        // fix cluster-cidr or custom flannel conf, regenerate conf, restart
    }
}

Prevention

Keep cluster-cidr consistent across server and agents
If overriding flannel conf, always include a Network field matching the cluster's IPv4 CIDR
Validate config.yaml: every dual-stack cluster must carry one IPv4 and one IPv6 CIDR

When it happens

Trigger: Cluster CIDR includes an IPv4 block but the generated/overridden flannel configuration has an empty Network (e.g. a custom flannel conf missing the Network field); mixing an IPv6-only custom flannel conf with a dual-stack/IPv4 cluster-cidr; partial config where the IPv4 CIDR was dropped before flannel init.

Common situations: Admins supply --flannel-conf / a custom flannel config file without a Network key while the cluster is IPv4 or dual-stack; migration from IPv6-only to dual-stack where the old conf is reused; agent joining with different cluster-cidr than the server.

Related errors

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