cloudflare/cloudflared · error

datagram provided is an invalid size

Error message

datagram provided is an invalid size

What it means

ErrDatagramPayloadInvalidSize is returned by UDPSessionPayloadDatagram.UnmarshalBinary when the incoming byte slice is either shorter than DatagramPayloadHeaderLen or longer than maxPayloadPlusHeaderLen. The parser must be able to read the fixed header and the declared payload within the slice bounds, so out-of-range sizes are rejected before parsing. It indicates a malformed or truncated datagram.

Source

Thrown at quic/v3/datagram_errors.go:13

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 datagram length against DatagramPayloadHeaderLen..maxPayloadPlusHeaderLen before calling UnmarshalBinary
2. Ensure the full QUIC datagram frame bytes are passed in one piece — do not split or reassemble them
3. Log the actual received length on errors.Is(err, v3.ErrDatagramPayloadInvalidSize) to detect malformed peers

Example fix

// before
unmarshaled := v3.UDPSessionPayloadDatagram{}
err = unmarshaled.UnmarshalBinary(payload[:16]) // truncated
// after
if len(payload) >= DatagramPayloadHeaderLen && len(payload) <= maxPayloadPlusHeaderLen {
    err = unmarshaled.UnmarshalBinary(payload)
}

func canUnmarshalPayload(data []byte) bool {
    return len(data) >= DatagramPayloadHeaderLen && len(data) <= maxPayloadPlusHeaderLen
}

func isWellSizedDatagram(data []byte) bool {
    return len(data) >= DatagramPayloadHeaderLen && len(data) <= maxPayloadPlusHeaderLen
}

if err := d.UnmarshalBinary(data); errors.Is(err, v3.ErrDatagramPayloadInvalidSize) {
    logger.Debug().Int("len", len(data)).Msg("dropping malformed datagram")
    return
}

When it happens

Trigger: Calling UnmarshalBinary on a buffer shorter than DatagramPayloadHeaderLen (e.g. payload[:16] when the header requires more), or a buffer exceeding maxPayloadPlusHeaderLen.

Common situations: Truncated datagrams received over the network; splitting datagrams at the wrong offset; feeding non-datagram garbage bytes into the parser; off-by-one slicing in test harnesses.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• datagram response is an invalid size
• 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 response message is an invalid size

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