Hmbown/CodeWhale · error · BodyReadError

payload too large

Error message

payload too large

What it means

readBoundedBody streams the request body and accumulates a byte count. When the total exceeds maxBytes it throws BodyReadError(413) immediately, so oversized payloads are cut off without buffering the whole body.

Solutions

1. Reduce the request body size below the route's maxBytes limit.
2. Increase the maxBytes argument at the call site if the route legitimately needs larger bodies.
3. Ensure the client sends the payload to the correct endpoint (large uploads belong on an upload route, not the bounded form route).

Example fix

// before
const body = await readBoundedBody(request, 4 * 1024);
// after
const body = await readBoundedBody(request, 16 * 1024);

// Client-side precheck before sending
if (new TextEncoder().encode(body).byteLength > MAX_BYTES) {
  throw new Error(`body exceeds ${MAX_BYTES} byte limit`);
}

try {
  const body = await readBoundedBody(request, MAX);
} catch (err) {
  if (err instanceof BodyReadError && err.status === 413) {
    return new Response("payload too large", { status: 413 });
  }
  throw err;
}

When it happens

Trigger: Any request whose streaming body bytes exceed the maxBytes limit passed to readBoundedBody — typically a login/admin form POST larger than the configured cap, even if Content-Length was absent or lying.

Common situations: Uploading a large body to a route meant for small form posts; a client with chunked encoding bypassing the Content-Length early check; a maxBytes configured smaller than the legitimate payload size after a config change.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• ${cause.message}
• expected application/x-www-form-urlencoded
• header name cannot be empty
• header name cannot be empty
• invalid Content-Length

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/b617d0ed632475e0. Report an issue: GitHub.

Appendix: source

Thrown at web/lib/bounded-body.ts:29

    try { await request.body?.cancel(message); } catch { /* Keep the original rejection. */ }
    throw new BodyReadError(status, message);
  };
  const rawLength = request.headers.get("content-length");
  if (rawLength !== null) {
    if (!/^\d+$/.test(rawLength)) return reject(400, "invalid Content-Length");
    if (Number(rawLength) > maxBytes) return reject(413, "payload too large");
  }
  if (!request.body) return new Uint8Array();

  const reader = request.body.getReader();
  const chunks: Uint8Array[] = [];
  let total = 0;
  try {
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      total += value.byteLength;
      if (total > maxBytes) throw new BodyReadError(413, "payload too large");
      chunks.push(value);
    }
  } catch (cause) {
    try { await reader.cancel("body rejected"); } catch { /* Preserve the read/size error. */ }
    throw cause instanceof BodyReadError ? cause : new BodyReadError(400, "body read failed");
  } finally {
    reader.releaseLock();
  }
  const bytes = new Uint8Array(total);
  let offset = 0;
  for (const chunk of chunks) {
    bytes.set(chunk, offset);
    offset += chunk.byteLength;
  }
  return bytes;
}

View on GitHub (pinned to 433685b202)