{"record":{"id":"637ded31212262ef","repo":"cilium/cilium","slug":"big-tcp-in-tunneling-mode-requires-pending-kernel","errorCode":null,"errorMessage":"BIG TCP in tunneling mode requires pending kernel support","messagePattern":"BIG TCP in tunneling mode requires pending kernel support","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/datapath/linux/bigtcp/bigtcp.go","lineNumber":268,"sourceCode":"\tDaemonConfig *option.DaemonConfig\n\tUserConfig   UserConfig\n\tIPsecConfig  ipsec.Config\n\tLBConfig     loadbalancer.Config\n\tTunnelConfig tunnel.Config\n\tDB           *statedb.DB\n\tDevices      statedb.Table[*tables.Device]\n}\n\nfunc validateConfig(cfg UserConfig, daemonCfg *option.DaemonConfig, ipsecCfg ipsec.Config, tunnelConfig tunnel.Config, dsrDispatch string, bigtcpTunnel bool) error {\n\tif cfg.EnableIPv6BIGTCP || cfg.EnableIPv4BIGTCP {\n\t\t// Check all configurations where Cilium creates tunnel devices\n\t\t// that don't support BIG TCP.\n\t\tif dsrDispatch == loadbalancer.DSRDispatchIPIP {\n\t\t\treturn errors.New(\"bpf-lb-dsr-dispatch ipip creates IPIP tunnels that aren't compatible with BIG TCP\")\n\t\t}\n\t\tif !bigtcpTunnel {\n\t\t\tif tunnelConfig.EncapProtocol() != tunnel.Disabled {\n\t\t\t\treturn errors.New(\"BIG TCP in tunneling mode requires pending kernel support\")\n\t\t\t}\n\t\t\tif dsrDispatch != loadbalancer.DSRDispatchOption {\n\t\t\t\treturn errors.New(\"BIG TCP with bpf-lb-dsr-dispatch geneve requires pending kernel support\")\n\t\t\t}\n\t\t}\n\n\t\tif ipsecCfg.Enabled() {\n\t\t\treturn errors.New(\"BIG TCP is not supported with encryption enabled\")\n\t\t}\n\t\tif daemonCfg.UnsafeDaemonConfigOption.EnableHostLegacyRouting {\n\t\t\treturn errors.New(\"BIG TCP is not supported with legacy host routing\")\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc newBIGTCP(lc cell.Lifecycle, p params) (Config, error) {\n\tbigtcpTunnel := supportsBIGTCPTunnel(p.Log)","sourceCodeStart":250,"sourceCodeEnd":286,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/datapath/linux/bigtcp/bigtcp.go#L250-L286","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before\n--tunnel-protocol=vxlan --enable-ipv4-big-tcp=true  (kernel lacks support)\n// after\n--tunnel-protocol=disabled --enable-ipv4-big-tcp=true  (native routing)","handlingStrategy":"validation","validationCode":"if (cfg.EnableIPv4BIGTCP || cfg.EnableIPv6BIGTCP) && tunnelConfig.EncapProtocol() != tunnel.Disabled {\n    if !kernelSupportsBIGTCPTunnel() {\n        return errors.New(\"kernel does not support BIG TCP with tunneling\")\n    }\n}","typeGuard":null,"tryCatchPattern":"if _, err := newBIGTCP(lc, params); err != nil {\n    if strings.Contains(err.Error(), \"tunneling mode requires pending kernel support\") {\n        log.Warn(\"upgrade kernel or disable BIG TCP in tunnel mode\")\n    }\n    return err\n}","preventionTips":["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"],"tags":["cilium","bigtcp","tunneling","kernel","config-validation"],"backgroundTag":"kernel-feature-not-supported","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}