BIG TCP in tunneling mode requires pending kernel support

Error message

BIG TCP in tunneling mode requires pending kernel support

What it means

Returned by validateConfig when BIG TCP is enabled with tunneling (EncapProtocol != tunnel.Disabled) but bigtcpTunnel is false, meaning the kernel lacks the support needed for BIG TCP on tunnel devices in tunneling mode. Cilium refuses to enable BIG TCP since tunnel devices would break the larger MTU/GSO guarantees.

Source

Thrown at pkg/datapath/linux/bigtcp/bigtcp.go:268

	DaemonConfig *option.DaemonConfig
	UserConfig   UserConfig
	IPsecConfig  ipsec.Config
	LBConfig     loadbalancer.Config
	TunnelConfig tunnel.Config
	DB           *statedb.DB
	Devices      statedb.Table[*tables.Device]
}

func validateConfig(cfg UserConfig, daemonCfg *option.DaemonConfig, ipsecCfg ipsec.Config, tunnelConfig tunnel.Config, dsrDispatch string, bigtcpTunnel bool) error {
	if cfg.EnableIPv6BIGTCP || cfg.EnableIPv4BIGTCP {
		// Check all configurations where Cilium creates tunnel devices
		// that don't support BIG TCP.
		if dsrDispatch == loadbalancer.DSRDispatchIPIP {
			return errors.New("bpf-lb-dsr-dispatch ipip creates IPIP tunnels that aren't compatible with BIG TCP")
		}
		if !bigtcpTunnel {
			if tunnelConfig.EncapProtocol() != tunnel.Disabled {
				return errors.New("BIG TCP in tunneling mode requires pending kernel support")
			}
			if dsrDispatch != loadbalancer.DSRDispatchOption {
				return errors.New("BIG TCP with bpf-lb-dsr-dispatch geneve requires pending kernel support")
			}
		}

		if ipsecCfg.Enabled() {
			return errors.New("BIG TCP is not supported with encryption enabled")
		}
		if daemonCfg.UnsafeDaemonConfigOption.EnableHostLegacyRouting {
			return errors.New("BIG TCP is not supported with legacy host routing")
		}
	}
	return nil
}

func newBIGTCP(lc cell.Lifecycle, p params) (Config, error) {
	bigtcpTunnel := supportsBIGTCPTunnel(p.Log)

View on GitHub (pinned to ac7b90affa)

Solutions

Upgrade the kernel to a version supporting BIG TCP in tunneling mode, then restart the agent
Switch to native routing (--tunnel=disabled with auto-direct-routing) where BIG TCP is fully supported
Disable BIG TCP if you must stay on tunneling with an unsupported kernel
Check cilium sysdump/kernel config for required GSO/GRO features on tunnel devices

Example fix

// before
--tunnel-protocol=vxlan --enable-ipv4-big-tcp=true  (kernel lacks support)
// after
--tunnel-protocol=disabled --enable-ipv4-big-tcp=true  (native routing)

Defensive patterns

Strategy: validation

Validate before calling

if (cfg.EnableIPv4BIGTCP || cfg.EnableIPv6BIGTCP) && tunnelConfig.EncapProtocol() != tunnel.Disabled {
    if !kernelSupportsBIGTCPTunnel() {
        return errors.New("kernel does not support BIG TCP with tunneling")
    }
}

Try / catch

if _, err := newBIGTCP(lc, params); err != nil {
    if strings.Contains(err.Error(), "tunneling mode requires pending kernel support") {
        log.Warn("upgrade kernel or disable BIG TCP in tunnel mode")
    }
    return err
}

Prevention

Check kernel version requirements for tunnel BIG TCP before enabling (>= 6.x with GSO-on-tunnel patches)
Prefer native routing when BIG TCP is a requirement
Pin node images/AMIs to tested kernel versions for Cilium
Test BIG TCP in a staging tunnel-mode cluster before enabling in production

When it happens

Trigger: Running with encapsulation enabled (e.g. --tunnel-protocol=vxlan/geneve) plus --enable-big-tcp on a kernel (or Cilium build) without the required tunnel-mode BIG TCP support (bigtcpTunnel flag false).

Common situations: Default VXLAN deployments where BIG TCP was turned on expecting kernel support; older kernels (< required version for tunnel BIG TCP); custom kernel builds without the relevant patches.

Related errors

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/637ded31212262ef. Report an issue: GitHub.