microsoft/garnet · error · Exception

Payload length {payloadLength} is larger than bufferSize {ne

Error message

Payload length {payloadLength} is larger than bufferSize {networkBufferSettings.sendBufferSize} bytes

What it means

In the bulk-payload writer (used by cluster migration / slot transfer commands that embed key addresses plus a value), GarnetClientSession throws when payloadLength exceeds networkBufferSettings.sendBufferSize. The send buffer must be able to hold the entire bulk string in one TryWriteBulkString call (step 8), so a payload larger than the configured send buffer is unrecoverable on the current connection settings. The check fires after the array-item address headers are written but before the value bytes.

Source

Thrown at libs/client/ClientSession/GarnetClientSession.cs:544

            // 6
            while (!RespWriteUtils.TryWriteArrayItem(currentAddress, ref curr, end))
            {
                Flush();
                curr = offset;
            }
            offset = curr;

            // 7
            while (!RespWriteUtils.TryWriteArrayItem(nextAddress, ref curr, end))
            {
                Flush();
                curr = offset;
            }
            offset = curr;

            if (payloadLength > networkBufferSettings.sendBufferSize)
                throw new Exception($"Payload length {payloadLength} is larger than bufferSize {networkBufferSettings.sendBufferSize} bytes");

            // 8
            while (!RespWriteUtils.TryWriteBulkString(new Span<byte>((void*)payloadPtr, payloadLength), ref curr, end))
            {
                Flush();
                curr = offset;
            }
            offset = curr;
        }

        /// <summary>
        /// Throttle the network sender, potentially blocking
        /// </summary>
        public void Throttle()
            => networkSender.Throttle();

        /// <summary>
        /// Flush current buffer of outgoing messages. Optionally spin-wait for all responses to be received and processed.

View on GitHub (pinned to 951b0fc683)

Solutions

1. Increase networkBufferSettings.sendBufferSize so it exceeds the largest single payload you transfer.
2. Split or chunk large values so each transfer fits within the configured buffer.
3. Avoid routing oversized object migrations through the session API; use a bulk path with streaming if available.

Example fix

// before — default buffer too small for large value migration
var settings = new NetworkBufferSettings(sendBufferSize: 16 * 1024);

// after — size the send buffer above the maximum single payload
var settings = new NetworkBufferSettings(sendBufferSize: 4 * 1024 * 1024);

// Reject payloads larger than the configured send buffer before issuing the command
if (payloadLength > networkBufferSettings.sendBufferSize)
    throw new InvalidOperationException("payload exceeds send buffer; increase buffer or chunk the value");

if (value.Length > maxPayloadForBuffer) { /* chunk or skip */ }

try { session.SendLargePayload(value); }
catch (Exception ex) when (ex.Message.Contains("larger than bufferSize")) { /* resize buffer or chunk */ }

When it happens

Trigger: Issuing a command that transfers a value whose byte length is greater than the negotiated/configured send buffer size (default sized by NetworkBufferSettings.sendBufferSize); typically cluster slot migration (MIGRATE/SETSLOT) of a large object via the session.

Common situations: Migrating large keys/values through GarnetClientSession with a small send buffer; default buffer size lowered for memory savings; transferring blobs larger than the page/buffer budget.

Related errors

• Failed to connect at {EndPoint}
• GarnetClientSession
• Unexpected response: {response}]
• Getting handle in disposed device
• Throttle count is negative

AI-assisted analysis of microsoft/garnet@951b0fc683 (2026-08-13). Data as JSON: /api/errors/e4231ff5676450e2. Report an issue: GitHub.