{"record":{"id":"18ceb0c68896e088","repo":"cilium/cilium","slug":"mismatched-buffer-margins-on-peer-link-s-s-d","errorCode":null,"errorMessage":"mismatched buffer margins on peer link %s (%s:%d %s:%d)","messagePattern":"mismatched buffer margins on peer link (.+?) \\((.+?):(.+?) (.+?):(.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/datapath/connector/netkit.go","lineNumber":147,"sourceCode":"\t\treturn nil, fmt.Errorf(\"unable to lookup netkit peer link: %w\", err)\n\t}\n\n\tpeerDevice, ok := peerLink.(*netlink.Netkit)\n\tif !ok {\n\t\treturn nil, fmt.Errorf(\"peer link does not appear to be a Netkit device\")\n\t}\n\n\t// Verify we have the correct buffer margins configured. We accept a margin that\n\t// is greater than what we requested, just in case it's ever rounded or aligned\n\t// within the kernel.\n\tif hostDevice.Headroom < cfg.DeviceHeadroom || hostDevice.Tailroom < cfg.DeviceTailroom {\n\t\tlogger.Warn(\"unexpected buffer margins on host link\",\n\t\t\tlogfields.Device, cfg.HostIfName,\n\t\t\tlogfields.DeviceHeadroom, hostDevice.Headroom,\n\t\t\tlogfields.DeviceTailroom, hostDevice.Tailroom)\n\t}\n\tif peerDevice.Headroom != hostDevice.Headroom || peerDevice.Tailroom != hostDevice.Tailroom {\n\t\treturn nil, fmt.Errorf(\"mismatched buffer margins on peer link %s (%s:%d %s:%d)\",\n\t\t\tcfg.PeerIfName,\n\t\t\tlogfields.DeviceHeadroom, peerDevice.Headroom,\n\t\t\tlogfields.DeviceTailroom, peerDevice.Tailroom)\n\t}\n\n\treturn peerLink, nil\n}\n","sourceCodeStart":129,"sourceCodeEnd":155,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/datapath/connector/netkit.go#L129-L155","documentation":"validateNetkitPair compares headroom/tailroom buffer margins of the peer link against the host link and requires them to be equal. This error is returned when the kernel reports mismatched margins between the two ends of the netkit pair. The library enforces this because asymmetric buffer margins can break datapath assumptions about packet head/tail space.","triggerScenarios":"The kernel rounded or aligned headroom/tailroom differently for the peer device than the host device; LinkConfig.DeviceHeadroom/DeviceTailroom requested values that the kernel applied inconsistently; a kernel version with differing netkit margin semantics.","commonSituations":"Backport/custom kernels that handle netkit headroom alignment differently; running with non-default DeviceHeadroom settings; kernel regression between host upgrades.","solutions":["Upgrade the kernel to a version with consistent netkit margin handling (>= 6.7 stable)","Reset DeviceHeadroom/DeviceTailroom in LinkConfig to defaults (0) and retry","Read the device/headroom/tailroom values in the error message and compare with 'ip -d link' output to confirm kernel-reported values","File/consult an issue for the kernel version if mismatch persists with default settings"],"exampleFix":"// before\ncfg := connector.LinkConfig{..., DeviceHeadroom: 256, DeviceTailroom: 256}\n// after\ncfg := connector.LinkConfig{..., DeviceHeadroom: 0, DeviceTailroom: 0}","handlingStrategy":"validation","validationCode":"if l, err := netlink.LinkByName(peerIfName); err == nil {\n    if nk, ok := l.(*netlink.Netkit); ok {\n        log.Printf(\"peer margins: headroom=%d tailroom=%d\", nk.Headroom, nk.Tailroom)\n    }\n}","typeGuard":null,"tryCatchPattern":"peer, err := setupNetkitPair(logger, cfg)\nif err != nil {\n    if strings.Contains(err.Error(), \"mismatched buffer margins\") {\n        // retry with default headroom/tailroom settings\n    }\n    return err\n}","preventionTips":["Use default DeviceHeadroom/DeviceTailroom (0) unless required","Pin to a stable, known-good kernel version","Verify kernel-reported margins with 'ip -d link' during bring-up","Track kernel-version-specific netkit behavior in CI matrix"],"tags":["network","netkit","buffer-margins","kernel"],"backgroundTag":"netkit-margin-mismatch","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}