ErrLookup › Background articles › payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads

payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads

"Payload too large", "request exceeds the maximum size", "exceeds max bytes" — errors from libraries that refuse to process a body, frame, or field because its size (in bytes or characters) crosses a deliberate cap. This article explains where these caps live, why they exist (memory guards, gzip/snappy bomb defenses, context-window and UI protection), and the general ways to fix them: shrink, chunk, reference instead of inline, or tune the limit on the right side.

Distilled from 97 documented records across 50 repositories.

Background

This family gathers errors raised when a producer-side size check fires before the payload is processed: a request body, a wire frame, a serialized field, or a decompressed blob exceeds a cap the library enforces. The checks share a shape — measure the payload (bytes via byteLength/bytesize/len, or characters via string length), compare against a constant or config value, and reject with a message that reports both actual and maximum sizes (e.g. Hadoop's "tried to deserialize {} bytes of data, but maxLength = {}", Navidrome's "payload size %d exceeds maximum of %d bytes"). The rejection happens early, often before any parsing, decompression, or allocation of the real payload.

The caps exist for several distinct reasons. One is memory-exhaustion defense: Hadoop's readString guards and RustFS's 1 MiB scanner-state bound exist so a corrupt or hostile length prefix cannot trigger a huge allocation and OOM. A closely related variant is decompression-bomb protection: LiveKit caps gzip-decompressed join requests at 1 MiB with a LimitReader, MLflow reads at most max_size+1 bytes of the zstd-expanded gateway body, and VictoriaMetrics refuses snappy blocks whose header declares a decoded length above maxDataSizeBytes. Another reason is protecting a downstream consumer's budget: OpenAI Codex caps queued text at 1,048,576 characters so one message cannot monopolize the model context window, ChromaCloud warns when a chunk exceeds the cloud provider's 16,384-character document quota, and Rocket.Chat charges every MCP tool response in a batch to a shared 5 MiB budget.

From the caller's side the error is deterministic and content-driven: the same payload fails the same way every time, and the message usually states both numbers so you can measure the distance to the cap. Whether it is recoverable varies. Some checks are warnings or graceful degradation (AnythingLLM's ChromaCloud oversize notice, AnotherRedisDesktopManager's read-only ViewerOverSize, Hmbown/CodeWhale's OSC 52 clipboard fallback refusal), some abort a batch or session (buzz-agent terminates the stdio reader loop, claude-mem's push stalls that sync lane until the offending row is removed), and some are plain HTTP 413/422-style rejections (Sure's {error: 'file_too_large'} on a 10 MB CSV upload).

The family also varies in what is measured and which side can tune it. Byte-based caps (Sure's bytesize check, Navidrome's 1 MB task payload, buzz-agent's BUZZ_AGENT_MAX_LINE_BYTES) hit multi-byte UTF-8 and base64 content sooner than character-based ones (Codex counts chars over Text items only). Some limits are frozen constants with no runtime knob (Sure's Import::MAX_CSV_SIZE, RustFS's 256 KiB redaction budget, mise's MAX_ACTION_PREDICTION_PAYLOAD), while others are configurable (Hadoop's ipc.maximum.response.length, MLFLOW_GATEWAY_MAX_DECOMPRESSED_REQUEST_SIZE, buzz-agent's env var). Units matter too: caps may apply per item (a single Chroma chunk), per frame (one SSE event under 8 MiB in CodeWhale), per request (LiveKit's join body), or cumulatively across a batch (Rocket.Chat's shared MCP budget).

Common causes

What usually fixes it

Go deeper

Documented occurrences

…and 77 more across the corpus — use search.

Honest provenance: generated on 2026-09-03 from AI-assisted analysis of the linked records. See how records are made.