cloudflare/cloudflared · error

ErrDatagramICMPPayloadTooLarge

ErrDatagramICMPPayloadTooLarge

Error message

datagram icmp payload exceeds %d bytes

What it means

ErrDatagramICMPPayloadTooLarge indicates an ICMPDatagram payload exceeds the protocol limit maxICMPPayloadLen. MarshalBinary returns it when len(d.Payload) > maxICMPPayloadLen (refusing to serialize an oversized ICMP datagram), and UnmarshalBinary returns it when the datagram body after the type byte (data[1:]) exceeds maxDatagramPayloadLen. Both wrap it via wrapMarshalErr/wrapUnmarshalErr, so match with errors.Is.

Source

Thrown at quic/v3/datagram_errors.go:18

package v3

import (
	"errors"
	"fmt"
)

var (
	ErrInvalidDatagramType                 error = errors.New("invalid datagram type expected")
	ErrDatagramHeaderTooSmall              error = fmt.Errorf("datagram should have at least %d byte", datagramTypeLen)
	ErrDatagramPayloadTooLarge             error = errors.New("payload length is too large to be bundled in datagram")
	ErrDatagramPayloadHeaderTooSmall       error = errors.New("payload length is too small to fit the datagram header")
	ErrDatagramPayloadInvalidSize          error = errors.New("datagram provided is an invalid size")
	ErrDatagramResponseMsgInvalidSize      error = errors.New("datagram response message is an invalid size")
	ErrDatagramResponseInvalidSize         error = errors.New("datagram response is an invalid size")
	ErrDatagramResponseMsgTooLargeMaximum  error = fmt.Errorf("datagram response error message length exceeds the length of the datagram maximum: %d", maxResponseErrorMessageLen)
	ErrDatagramResponseMsgTooLargeDatagram error = fmt.Errorf("datagram response error message length exceeds the length of the provided datagram")
	ErrDatagramICMPPayloadTooLarge         error = fmt.Errorf("datagram icmp payload exceeds %d bytes", maxICMPPayloadLen)
	ErrDatagramICMPPayloadMissing          error = errors.New("datagram icmp payload is missing")
)

func wrapMarshalErr(err error) error {
	return fmt.Errorf("datagram marshal error: %w", err)
}

func wrapUnmarshalErr(err error) error {
	return fmt.Errorf("datagram unmarshal error: %w", err)
}

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Before marshaling, check len(d.Payload) <= maxICMPPayloadLen and truncate or reject the ICMP payload.
2. Use errors.Is(err, v3.ErrDatagramICMPPayloadTooLarge) to drop oversized ICMP datagrams without failing the session.
3. Reduce the size of ICMP probes sent through the tunnel (e.g. smaller ping payload size).
4. Ensure the peer caps ICMP datagram bodies at the same maxDatagramPayloadLen.

Example fix

// before
data, err := icmpDatagram.MarshalBinary()
// after
if len(icmpDatagram.Payload) > v3.MaxICMPPayloadLen {
    return nil, fmt.Errorf("icmp payload too large: %d bytes", len(icmpDatagram.Payload))
}
data, err := icmpDatagram.MarshalBinary()

if len(icmpDatagram.Payload) > v3.MaxICMPPayloadLen {
    return fmt.Errorf("icmp payload %d exceeds max %d", len(icmpDatagram.Payload), v3.MaxICMPPayloadLen)
}

if errors.Is(err, v3.ErrDatagramICMPPayloadTooLarge) {
    logger.Warn().Msg("oversized ICMP datagram; dropping")
    return nil
}

When it happens

Trigger: MarshalBinary on an ICMPDatagram whose Payload field exceeds maxICMPPayloadLen; UnmarshalBinary on an ICMP datagram whose received body (data[1:]) exceeds maxDatagramPayloadLen — e.g. an oversized ICMP probe or a peer violating the size cap.

Common situations: Applications proxying large ICMP packets (big ping payloads) through the tunnel; mixing maximum transfer-unit assumptions between versions; fuzzed/malicious traffic with oversized ICMP bodies; tests verifying the size cap.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• datagram icmp payload is missing
• ErrDatagramResponseMsgTooLargeMaximum
• invalid datagram type expected
• payload length is too large to be bundled in datagram
• payload length is too small to fit the datagram header

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/8831e5821c3aa07e. Report an issue: GitHub.