What causes "Bridge response body exceeded the configured size limit." in paperclipai/paperclip?

Reduce the response body returned by the handler (paginate, truncate, or stream to a file and return a reference).

Bridge response body exceeded the configured size limit.

Error message

Bridge response body exceeded the configured size limit.

What it means

The sandbox callback bridge handler produced a response whose body is larger than maxBodyBytes, the configured per-message body cap for the bridge. The bridge enforces this before encoding the response so a single oversized handler reply cannot balloon the process memory ledger or the on-disk envelope. The error is thrown inside the host-side handler wrapper and surfaces to the sandbox caller as a bridge handler failure.

Solutions

Reduce the response body returned by the handler (paginate, truncate, or stream to a file and return a reference).
Raise the bridge's maxBodyBytes configuration to fit the largest legitimate handler response.
Return a non-2xx status with a small JSON error body instead of embedding the large payload.

Example fix

// before
return { status: 200, body: largeFileBuffer.toString("utf8") };
// after
if (largeFileBuffer.byteLength > maxBodyBytes) {
  return { status: 413, body: JSON.stringify({ error: "payload too large", savedTo: scratchPath }) };
}
return { status: 200, body: largeFileBuffer.toString("utf8") };

Defensive patterns

Strategy: validation

Validate before calling

const bytes = Buffer.byteLength(result.body ?? "");
if (bytes > maxBodyBytes) return { status: 413, body: JSON.stringify({ error: "response too large" }) };

Type guard

const fitsBridgeLimit = (body: unknown, max: number): boolean =>
  body == null || Buffer.byteLength(typeof body === "string" ? body : String(body)) <= max;

Try / catch

try { return await bridge.dispatch(req); } catch (e) { if (e.message.includes("size limit")) return { status: 413, body: "response too large" }; throw e; }

Prevention

Truncate or chunk handler responses before returning them
Keep maxBodyBytes in sync with the largest known handler output
Return file references instead of inline blobs for big payloads
Account for base64 encoding overhead (~33%) when sizing bodies

When it happens

Trigger: A registered input.handleRequest callback returns { body } whose Buffer.byteLength exceeds maxBodyBytes for a sandbox bridge request.

Common situations: A handler echoes back a large file, log blob, or generated artifact; maxBodyBytes was lowered in config while existing handlers still return big payloads; base64-encoded responses inflate ~33% past the raw limit.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

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

Appendix: source

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

      // retry, so do not run the mutation; the retry then applies it once. When
      // the handler claims first, the recovery path leaves the request alone and
      // the handler writes the real response.
      if (!claimForHandler()) {
        return;
      }

      // Build the response, then finalize once. The handler already holds the
      // claim, so `finalize` writes the real response.
      let response: SandboxCallbackBridgeResponse;
      let handlerReturned = false;
      try {
        const { bodyEncoding, ...forwardRequest } = request;
        const result = await input.handleRequest({ ...forwardRequest,
          body: bodyEncoding === "base64" ? decodeSandboxBridgeBody(request, maxBodyBytes) : request.body,
        }, { signal: guard.controller.signal, reservation });
        handlerReturned = true;
        const responseBytes = Buffer.byteLength(result.body ?? "");
        if (responseBytes > maxBodyBytes) throw new Error("Bridge response body exceeded the configured size limit.");
        if (!reservation.reserve(4 * sandboxBridgeEnvelopeLimit(responseBytes))) {
          throw new Error("Bridge host response body capacity is busy.");
        }
        const responseBody = encodeSandboxBridgeBody(result.body ?? "", maxBodyBytes);
        response = {
          id: request.id,
          status: result.status,
          headers: result.headers ?? {},
          ...responseBody,
          completedAt: new Date().toISOString(),
        };
      } catch (error) {
        console.warn(
          `[paperclip] sandbox callback bridge handler failed for ${request.id}: ${error instanceof Error ? error.message : String(error)}`,
        );
        // Tell a worker abort apart from a normal handler failure. The recovery
        // path aborts `guard.controller` when the per-iteration timeout or the
        // watchdog fires. The abort reaches this catch only after the handler

View on GitHub (pinned to 3f1d897a7c)