cilium/cilium · error

mismatched buffer margins on peer link %s (%s:%d %s:%d)

Error message

mismatched buffer margins on peer link %s (%s:%d %s:%d)

What it means

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.

Source

Thrown at pkg/datapath/connector/netkit.go:147

		return nil, fmt.Errorf("unable to lookup netkit peer link: %w", err)
	}

	peerDevice, ok := peerLink.(*netlink.Netkit)
	if !ok {
		return nil, fmt.Errorf("peer link does not appear to be a Netkit device")
	}

	// Verify we have the correct buffer margins configured. We accept a margin that
	// is greater than what we requested, just in case it's ever rounded or aligned
	// within the kernel.
	if hostDevice.Headroom < cfg.DeviceHeadroom || hostDevice.Tailroom < cfg.DeviceTailroom {
		logger.Warn("unexpected buffer margins on host link",
			logfields.Device, cfg.HostIfName,
			logfields.DeviceHeadroom, hostDevice.Headroom,
			logfields.DeviceTailroom, hostDevice.Tailroom)
	}
	if peerDevice.Headroom != hostDevice.Headroom || peerDevice.Tailroom != hostDevice.Tailroom {
		return nil, fmt.Errorf("mismatched buffer margins on peer link %s (%s:%d %s:%d)",
			cfg.PeerIfName,
			logfields.DeviceHeadroom, peerDevice.Headroom,
			logfields.DeviceTailroom, peerDevice.Tailroom)
	}

	return peerLink, nil
}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Upgrade the kernel to a version with consistent netkit margin handling (>= 6.7 stable)
2. Reset DeviceHeadroom/DeviceTailroom in LinkConfig to defaults (0) and retry
3. Read the device/headroom/tailroom values in the error message and compare with 'ip -d link' output to confirm kernel-reported values
4. File/consult an issue for the kernel version if mismatch persists with default settings

Example fix

// before
cfg := connector.LinkConfig{..., DeviceHeadroom: 256, DeviceTailroom: 256}
// after
cfg := connector.LinkConfig{..., DeviceHeadroom: 0, DeviceTailroom: 0}

if l, err := netlink.LinkByName(peerIfName); err == nil {
    if nk, ok := l.(*netlink.Netkit); ok {
        log.Printf("peer margins: headroom=%d tailroom=%d", nk.Headroom, nk.Tailroom)
    }
}

peer, err := setupNetkitPair(logger, cfg)
if err != nil {
    if strings.Contains(err.Error(), "mismatched buffer margins") {
        // retry with default headroom/tailroom settings
    }
    return err
}

When it happens

Trigger: 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.

Common situations: Backport/custom kernels that handle netkit headroom alignment differently; running with non-default DeviceHeadroom settings; kernel regression between host upgrades.

Related errors

• unable to create netkit pair: %w
• netkit validation failed: %w
• netkit device probe failed, requires kernel 6.7.0+ and CONFI
• netkit driver missing scrub attributes, required with --%s=t
• netkit connector not available: %w

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