What causes "datagram unmarshal error: %w" in cloudflare/cloudflared?

Validate the received buffer length and structure before calling UnmarshalBinary.

datagram unmarshal error: %w

Error message

datagram unmarshal error: %w

What it means

wrapUnmarshalErr wraps errors that occur while deserializing a received QUIC v3 datagram. It adds the 'datagram unmarshal error' prefix to any parse failure surfaced by UnmarshalBinary, such as truncated or malformed input. Callers should unwrap to find the underlying sentinel error.

Source

Thrown at quic/v3/datagram_errors.go:27

	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

Validate the received buffer length and structure before calling UnmarshalBinary.
Unwrap with errors.Is against the ErrDatagram* sentinels to determine the exact parse failure.
Drop or log-and-ignore malformed datagrams rather than crashing the session.
Check both endpoints run a compatible cloudflared/protocol version.

Example fix

// before
err := dg.UnmarshalBinary(data)
// after
if err := dg.UnmarshalBinary(data); err != nil {
    if errors.Is(err, quicv3.ErrDatagramICMPPayloadMissing) {
        logger.Warn().Msg("dropping malformed datagram")
        return nil
    }
    return err
}

Defensive patterns

Strategy: try-catch

Validate before calling

if len(data) < minDatagramLen { return fmt.Errorf("datagram too short: %d", len(data)) }

Try / catch

if err := d.UnmarshalBinary(data); err != nil {
    logger.Warn().Err(err).Msg("dropping malformed datagram")
    return nil
}

Prevention

Validate buffer length before unmarshaling
Drop-and-log malformed datagrams instead of failing hard
Keep protocol versions aligned on both peers
Fuzz-test UnmarshalBinary with truncated inputs

When it happens

Trigger: Calling UnmarshalBinary on a byte slice that is truncated, corrupted, or otherwise fails the datagram's structural parsing.

Common situations: Receiving datagrams from a peer over a lossy/misbehaving path; protocol version mismatch producing misaligned parsing; reading a partially-flushed datagram buffer.

Understand the failure class

Background: "cannot parse invalid wire-format data", "cannot unmarshal", "failed unmarshalling": protobuf unmarshal errors explained — this error's family across 10 libraries.

Related errors

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