paperclipai/paperclip · error

Bridge body exceeded the configured size limit.

Error message

Bridge body exceeded the configured size limit.

What it means

encodeSandboxBridgeBody serializes a callback body for transport through the sandbox bridge and enforces a hard byte limit (maxBodyBytes). If Buffer.byteLength(body) exceeds that limit it throws instead of silently truncating, because downstream decoders and the envelope-size math (6x expansion + 64KiB metadata slack) assume bounded bodies.

Solutions

1. Measure the payload first (`Buffer.byteLength(body)`) and raise maxBodyBytes in the bridge configuration if the larger size is legitimate.
2. Truncate or chunk the payload at the call site before encoding (e.g. cap captured output to the configured limit).
3. Compress or summarize large content (base64 of compressed bytes still counts — reduce source bytes instead).
4. If huge bodies are expected regularly, switch the transport to a file/blob reference passed by path instead of inlining the body.

Example fix

// before
const envelope = encodeSandboxBridgeBody(hugeLog, maxBodyBytes); // throws
// after
const clipped = hugeLog.length > maxBodyBytes ? hugeLog.slice(0, maxBodyBytes) : hugeLog;
const envelope = encodeSandboxBridgeBody(clipped, maxBodyBytes);

const bytes = Buffer.isBuffer(body) ? body.length : Buffer.byteLength(body);
if (bytes > maxBodyBytes) body = body.slice(0, maxBodyBytes); // or truncate the string first

function withinBridgeLimit(body: string | Buffer, maxBodyBytes: number): boolean {
  return Buffer.byteLength(body) <= maxBodyBytes;
}

try {
  envelope = encodeSandboxBridgeBody(body, maxBodyBytes);
} catch (err) {
  if (err instanceof Error && err.message.includes("size limit")) {
    envelope = encodeSandboxBridgeBody(truncateToBytes(body, maxBodyBytes), maxBodyBytes);
  } else throw err;
}

When it happens

Trigger: Calling encodeSandboxBridgeBody(body, maxBodyBytes) with a string or Buffer whose UTF-8 byte length exceeds maxBodyBytes — e.g. large response payloads from process output, file contents, or accumulated logs routed through responseBody.

Common situations: Raising agent output limits without raising the bridge's configured max body size; an agent dumps a big file or verbose log into a callback; a caller passes an entire HTTP response body assuming the bridge will chunk it.

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

• Invalid bridge base64 body.
• Invalid bridge body.
• OpenCode SSE event exceeded the retained payload limit
• Unsupported bridge body encoding.
• A full lowercase source SHA is required.

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/da705c89ba68cbfa. Report an issue: GitHub.

Appendix: source

Thrown at packages/adapter-utils/src/sandbox-callback-bridge-body.ts:13

export interface SandboxCallbackBridgeBody {
  body: string;
  /** Omitted by older queue peers, whose bodies are UTF-8 text. */
  bodyEncoding?: "utf8" | "base64";
}

/** JSON can escape each input byte as six characters. Metadata is bounded too. */
export function sandboxBridgeEnvelopeLimit(maxBodyBytes: number): number {
  return 6 * maxBodyBytes + 64 * 1024;
}

export function encodeSandboxBridgeBody(body: string | Buffer, maxBodyBytes: number): SandboxCallbackBridgeBody {
  if (Buffer.byteLength(body) > maxBodyBytes) throw new Error("Bridge body exceeded the configured size limit.");
  return Buffer.isBuffer(body) ? { body: body.toString("base64"), bodyEncoding: "base64" } : { body };
}

/** Self-contained so the same decoder can be embedded in the remote gateway. */
export function decodeSandboxBridgeBody(envelope: SandboxCallbackBridgeBody, maxBodyBytes: number): Buffer {
  if (!envelope || typeof envelope.body !== "string") throw new Error("Invalid bridge body.");
  if (envelope.bodyEncoding === undefined || envelope.bodyEncoding === "utf8") {
    if (Buffer.byteLength(envelope.body, "utf8") > maxBodyBytes) throw new Error("Bridge body exceeded the configured size limit.");
    return Buffer.from(envelope.body, "utf8");
  }
  if (envelope.bodyEncoding !== "base64") throw new Error("Unsupported bridge body encoding.");
  const value = envelope.body;
  if (value.length > 4 * Math.ceil(maxBodyBytes / 3)) throw new Error("Bridge body exceeded the configured size limit.");
  // Buffer.from is permissive; reject malformed input before allocating bytes.
  if (value.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(value) || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
    throw new Error("Invalid bridge base64 body.");
  }
  const bytes = Buffer.from(value, "base64");

View on GitHub (pinned to 3f1d897a7c)