cloudflare/cloudflared · error

invalid payload size provided

Error message

invalid payload size provided

What it means

ErrInvalidPayloadDestLen is returned by RequestID.MarshalBinaryTo when the destination byte slice is smaller than the 16 bytes needed to hold the full request-id-v2 identifier. MarshalBinaryTo writes the hi/lo uint64 halves in big-endian order into data, so a short buffer would be overflowed; the library rejects it upfront.

Source

Thrown at quic/v3/request.go:17

package v3

import (
	"encoding/binary"
	"errors"
	"fmt"
)

const (
	datagramRequestIdLen = 16
)

var (
	// ErrInvalidRequestIDLen is returned when the provided request id can not be parsed from the provided byte slice.
	ErrInvalidRequestIDLen error = errors.New("invalid request id length provided")
	// ErrInvalidPayloadDestLen is returned when the provided destination byte slice cannot fit the whole request id.
	ErrInvalidPayloadDestLen error = errors.New("invalid payload size provided")
)

// RequestID is the request-id-v2 identifier, it is used to distinguish between specific flows or sessions proxied
// from the edge to cloudflared.
type RequestID uint128

type uint128 struct {
	hi uint64
	lo uint64
}

// RequestIDFromSlice reads a request ID from a byte slice.
func RequestIDFromSlice(data []byte) (RequestID, error) {
	if len(data) != datagramRequestIdLen {
		return RequestID{}, ErrInvalidRequestIDLen
	}

	return RequestID{

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Allocate the destination with at least 16 bytes: make([]byte, 16) or use RequestID's MarshalBinary which sizes it correctly.
2. Update any buffer-size constant from 8 to 16 after the request-id-v2 migration.
3. Guard with len(buf) >= 16 before the call, or pre-size from a shared constant (e.g. datagramRequestIdLen).
4. If using MarshalBinaryTo on a pooled buffer, verify the pool's buffer size matches the new 16-byte id width.

Example fix

// before
buf := make([]byte, 8)
err := id.MarshalBinaryTo(buf)
// after
buf := make([]byte, 16)
err := id.MarshalBinaryTo(buf)

buf := make([]byte, 16)
if len(buf) < 16 {
    return errors.New("destination buffer too small for request id")
}
err := id.MarshalBinaryTo(buf)

func fitsRequestID(buf []byte) bool { return len(buf) >= 16 }

if err := id.MarshalBinaryTo(buf); errors.Is(err, v3.ErrInvalidPayloadDestLen) {
    buf = make([]byte, 16)
    err = id.MarshalBinaryTo(buf)
}

When it happens

Trigger: Calling id.MarshalBinaryTo(buf) where cap/len(buf) < 16 — e.g. reusing a buffer sized for the old 8-byte request-id format, allocating make([]byte, 8), or slicing a larger buffer with a window shorter than 16 bytes.

Common situations: Migrating code from the previous 8-byte request id encoding to 16-byte request-id-v2 without resizing buffers; reusing pooled buffers sized by a constant that wasn't updated; passing a nil slice.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

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