Bridge response body exceeded the configured size limit of $

Error message

Bridge response body exceeded the configured size limit of ${maxBodyBytes} bytes.

What it means

Thrown inside the bridge request handler after handleRequest returns, when Buffer.byteLength(responseBody, "utf8") exceeds maxBodyBytes. The default limit is 256 KiB (DEFAULT_BRIDGE_MAX_BODY_BYTES = 256 * 1024); it can be overridden per bridge instance via the maxBodyBytes option. The throw is caught by the surrounding try/catch at sandbox-callback-bridge.ts:743, which writes a 502 response back to the caller with the error message in the body — so the caller sees a 502, not a stack trace, and the request file is removed.

Source

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

    const denialReason = await authorizeRequest(request);
    if (denialReason) {
      await writeBridgeResponse(input.client, requestPath, responsePath, {
        id: request.id,
        status: 403,
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ error: denialReason }),
        completedAt: new Date().toISOString(),
      });
      await input.client.remove(requestPath);
      return;
    }

    try {
      const result = await input.handleRequest(request);
      const responseBody = result.body ?? "";
      if (Buffer.byteLength(responseBody, "utf8") > maxBodyBytes) {
        throw new Error(`Bridge response body exceeded the configured size limit of ${maxBodyBytes} bytes.`);
      }
      await writeBridgeResponse(input.client, requestPath, responsePath, {
        id: request.id,
        status: result.status,
        headers: result.headers ?? {},
        body: 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)}`,
      );
      await writeBridgeResponse(input.client, requestPath, responsePath, {
        id: request.id,
        status: 502,
        headers: { "content-type": "application/json" },
        body: JSON.stringify({
          error: error instanceof Error ? error.message : String(error),

View on GitHub (pinned to 67001ec6eb)

Solutions

Reduce response body size in handleRequest: truncate, paginate, or stream instead of returning the full payload.
Raise the limit explicitly when constructing the bridge: startSandboxCallbackBridgePoller({ ..., maxBodyBytes: 2 * 1024 * 1024 }) for 2 MiB.
Inspect the resulting 502 response body the caller receives — it will contain this exact message, confirming the size cap as the cause.
If payloads are routinely large, switch the bridge to a side-channel transfer (write to a synced file, return a path) instead of inlining bytes in the JSON response.

Example fix

// before
startSandboxCallbackBridgePoller({
  client, handleRequest, directories,
  // default maxBodyBytes = 256 KiB
});
// handler returns a 2 MiB base64 payload -> 502

// after
startSandboxCallbackBridgePoller({
  client, handleRequest, directories,
  maxBodyBytes: 4 * 1024 * 1024,
});

Defensive patterns

Strategy: validation

Validate before calling

const MAX_BODY_BYTES = 256 * 1024; // mirror DEFAULT_BRIDGE_MAX_BODY_BYTES
function assertResponseBodySize(body: string, limit = MAX_BODY_BYTES): void {
  if (Buffer.byteLength(body, "utf8") > limit) {
    throw new Error(`Response body ${Buffer.byteLength(body, "utf8")} bytes exceeds limit ${limit}; paginate, truncate, or raise maxBodyBytes`);
  }
}

// inside handleRequest, before returning:
assertResponseBodySize(result.body ?? "");

Try / catch

// The bridge already converts this throw into a 502 response for the caller.
// In the handler, you can preempt it:
const body = await buildResponse(request);
if (Buffer.byteLength(body, "utf8") > (maxBodyBytes ?? 256 * 1024)) {
  return { status: 413, headers: { "content-type": "application/json" }, body: JSON.stringify({ error: "response too large" }) };
}

Prevention

Keep bridge responses under 256 KiB; offload larger payloads to a synced file and return a path reference.
If you need more, set maxBodyBytes explicitly when constructing the bridge.
Measure UTF-8 bytes (Buffer.byteLength), not string length — multi-byte content inflates faster than expected.
Add a unit test that asserts every handleRequest response stays under the configured cap.

When it happens

Trigger: A bridge handleRequest that returns a large body — verbose logs, full file dumps, large JSON payloads, base64-encoded binary. The check at sandbox-callback-bridge.ts:733-735 measures UTF-8 bytes after result.body ?? "", so multi-byte content (CJK, emoji) counts as more than its character length.

Common situations: Endpoints that stream or snapshot large outputs (build logs, screenshot base64, directory listings, model responses with long completions). Production runs that work fine until a single large payload trips the cap; defaults fit typical control messages but not bulk file transfer.

Related errors

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/2724bdb975ec2716. Report an issue: GitHub.