cloudflare/cloudflared · error

ErrDatagramResponseMsgTooLargeMaximum

ErrDatagramResponseMsgTooLargeMaximum

Error message

datagram response error message length exceeds the length of the datagram maximum: %d

What it means

ErrDatagramResponseMsgTooLargeMaximum is returned when unmarshaling a UDPSessionRegistrationResponseDatagram whose embedded error-message length field (a 16-bit value at bytes 18:20) exceeds maxResponseErrorMessageLen. The protocol caps how long an error message may be; a larger declared length means a malformed or non-conformant response datagram. UnmarshalBinary wraps this sentinel via wrapUnmarshalErr, so match with errors.Is.

Source

Thrown at quic/v3/datagram_errors.go:16

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. Validate the length field before unmarshaling: read data[18:20] and reject values > maxResponseErrorMessageLen.
2. Use errors.Is(err, v3.ErrDatagramResponseMsgTooLargeMaximum) to identify malformed peer responses and drop them.
3. Verify both endpoints run matching cloudflared/quic v3 protocol versions.
4. Log the remote address; repeated occurrences may indicate tampered or buggy traffic.

Example fix

// before
err := resp.UnmarshalBinary(payload)
if err != nil { return err }
// after
err := resp.UnmarshalBinary(payload)
if errors.Is(err, v3.ErrDatagramResponseMsgTooLargeMaximum) {
    logger.Warn().Msg("rejecting response datagram with oversized error message")
    return nil
}

if len(data) >= 20 && binary.BigEndian.Uint16(data[18:20]) > v3.MaxResponseErrorMessageLen {
    return fmt.Errorf("response error message length exceeds protocol maximum")
}

if errors.Is(err, v3.ErrDatagramResponseMsgTooLargeMaximum) {
    logger.Warn().Msg("malformed response datagram: message length exceeds maximum; dropping")
    return nil
}

When it happens

Trigger: UnmarshalBinary on a UDPSessionRegistrationResponseDatagram where the uint16 error-message length read from data[18:20] is greater than maxResponseErrorMessageLen — i.e. a response datagram crafted or corrupted with an oversized message-length field.

Common situations: Corrupted datagram in transit; an incompatible peer/protocol version writing extra data into the message field; malicious or fuzzed traffic; a test constructing a payload with a too-large length field to verify error handling.

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

• invalid datagram type expected
• ErrDatagramHeaderTooSmall
• ErrDatagramICMPPayloadTooLarge
• 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/f5dcce02e430157a. Report an issue: GitHub.