What causes "datagram should have at least %d byte" in cloudflare/cloudflared?

Check len(data) >= datagramTypeLen (1) before calling ParseDatagramType or UnmarshalBinary.

ErrDatagramHeaderTooSmall

ErrDatagramHeaderTooSmall

Error message

datagram should have at least %d byte

What it means

ErrDatagramHeaderTooSmall is a sentinel error in quic/v3/datagram_errors.go indicating that a datagram buffer is shorter than the single-byte datagram type header (datagramTypeLen). ParseDatagramType returns it when len(data) < 1, and UnmarshalBinary implementations surface it for empty or truncated inputs. It means the byte slice is too small to even identify the datagram type, so no parsing can proceed.

Solutions

Check len(data) >= datagramTypeLen (1) before calling ParseDatagramType or UnmarshalBinary.
Use errors.Is(err, v3.ErrDatagramHeaderTooSmall) to branch and skip/drop empty datagrams gracefully.
Trace where the buffer is produced; fix the length calculation that emitted a sub-header-sized slice.
Ensure the remote side always prefixes datagrams with the type byte.

Example fix

// before
err := datagram.UnmarshalBinary(buf)
// after
if len(buf) < v3.DatagramTypeLen {
    return fmt.Errorf("datagram too small: %d bytes", len(buf))
}
err := datagram.UnmarshalBinary(buf)
if errors.Is(err, v3.ErrDatagramHeaderTooSmall) {
    logger.Debug().Msg("dropping empty datagram")
    return nil
}

Defensive patterns

Strategy: type-guard

Validate before calling

if len(data) < 1 {
    return fmt.Errorf("empty datagram buffer")
}

Type guard

func hasDatagramHeader(data []byte) bool {
    return len(data) >= v3.DatagramTypeLen
}

Try / catch

if errors.Is(err, v3.ErrDatagramHeaderTooSmall) {
    logger.Debug().Msg("datagram too small to parse; skipping")
    return nil
}

Prevention

Never call ParseDatagramType/UnmarshalBinary on empty slices; short-circuit on len(data)==0.
Check read-loop return values: empty reads often mean the session closed.
Match sentinel errors with errors.Is, not string comparison.

When it happens

Trigger: Calling ParseDatagramType with an empty or nil slice; calling UnmarshalBinary on any v3 datagram type (e.g. UDPSessionRegistrationDatagram) with an empty byte slice; receiving a zero-length datagram over the session.

Common situations: Peer closed a stream/session and delivered an empty read; buffer-slicing math upstream chopped the header off; tests feeding []byte{} to validate error paths; a serialization bug producing empty payloads on the wire.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at quic/v3/datagram_errors.go:10

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)