cloudflare/cloudflared · error

datagram marshal error: %w

Error message

datagram marshal error: %w

What it means

wrapMarshalErr wraps any lower-level failure that occurs while serializing a datagram (payload or response message) in the QUIC v3 datagram layer. The library throws it to add a consistent 'datagram marshal error' prefix so callers can identify the serialization stage of failure. The wrapped cause is typically one of the ErrDatagram* sentinel errors, e.g. payload too large or missing ICMP payload.

Source

Thrown at quic/v3/datagram_errors.go:23

	"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. Reduce the payload size to fit within maxICMPPayloadLen before marshaling.
2. Allocate a destination slice large enough for the serialized message (check ErrDatagramResponseMsgTooLargeDatagram).
3. Unwrap with errors.Is against the ErrDatagram* sentinels to identify the exact cause and handle each case.
4. Log the wrapped error (%w chain) to confirm which sentinel was returned.

Example fix

// before
if err := datagram.MarshalPayloadHeaderTo(buf); err != nil { return err }
// after
if err := datagram.MarshalPayloadHeaderTo(buf); err != nil {
    if errors.Is(err, quicv3.ErrDatagramICMPPayloadTooLarge) {
        return fmt.Errorf("icmp payload too large, max %d bytes", quicv3.MaxICMPPayloadLen)
    }
    return err
}

if len(payload) > maxICMPPayloadLen { return fmt.Errorf("payload too large: %d", len(payload)) }

func fitsInDatagram(payload []byte, buf []byte) bool { return len(payload) <= maxICMPPayloadLen && cap(buf) >= len(payload) }

if err := d.MarshalBinary(); err != nil {
    switch {
    case errors.Is(err, quicv3.ErrDatagramICMPPayloadTooLarge): // shrink payload
    case errors.Is(err, quicv3.ErrDatagramResponseMsgTooLargeDatagram): // grow buffer
    default: return err
    }
}

When it happens

Trigger: Calling MarshalBinary or MarshalPayloadHeaderTo on a datagram whose payload exceeds maxICMPPayloadLen, whose response message length exceeds the provided datagram capacity, or whose ICMP payload is missing.

Common situations: Sending oversized ICMP probe payloads through a tunnel datagram session; passing a destination buffer smaller than the serialized response; constructing a datagram struct without populating the payload field.

Understand the failure class

Background: json.Marshal / "failed to marshal" errors in Go: why "unsupported type" happens and how to fix it — this error's family across 22 libraries.

Related errors

• invalid datagram type expected
• payload length is too large to be bundled in datagram
• payload length is too small to fit the datagram header
• datagram provided is an invalid size
• datagram response message is an invalid size

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