paperclipai/paperclip · error · BridgeProcessCapacityError

The bridge host reached its reserved process body byte ceili

Error message

The bridge host reached its reserved process body byte ceiling. Retry later.

What it means

While reading a bridge-forwarded response body stream, each chunk is reserved against a shared per-process byte ledger. This error is thrown when an incoming chunk would push the retained bytes past the configured maxBodyBytes limit, protecting the bridge host from unbounded response bodies.

Source

Thrown at packages/adapter-utils/src/execution-target.ts:1801

    return Buffer.alloc(0);
  }

  const reader = response.body.getReader();
  const chunks: Buffer[] = [];
  let totalBytes = 0;
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    if (!value) continue;
    const chunkBytes = value.byteLength;
    totalBytes += chunkBytes;
    if (totalBytes > maxBodyBytes) {
      await reader.cancel().catch(() => undefined);
      throw bridgeResponseBodyLimitError(maxBodyBytes);
    }
    if (reservation && !reservation.reserve(chunkBytes)) {
      await reader.cancel().catch(() => undefined);
      throw new BridgeProcessCapacityError();
    }
    chunks.push(Buffer.from(value));
  }
  if (reservation && !reservation.reserve(totalBytes)) {
    await reader.cancel().catch(() => undefined);
    throw new BridgeProcessCapacityError();
  }
  return Buffer.concat(chunks, totalBytes);
}

const PROCESS_SESSION_PROXY_SCRIPT = "paperclip-process-session-proxy.mjs";
const PROCESS_SESSION_REMOTE_SCRIPT = "paperclip-process-session-remote.mjs";
// The streamed variant writes its output frames to stdout, so it rides a
// separate remote path. A sandbox can hold both scripts without the content
// hash-skip gate thrashing when a run switches output mode.
const PROCESS_SESSION_REMOTE_STREAM_SCRIPT = "paperclip-process-session-remote-stream.mjs";
const PROCESS_SESSION_AUTH_TIMEOUT_MS = 5_000;
// The bounded budget `stop()` waits for the wrapper's `shutdownAck` event

View on GitHub (pinned to 01ad858492)

Solutions

Increase the bridge's maxBodyBytes / body-limit configuration to accommodate expected payloads.
Chunk large downloads so no single forwarded response exceeds the limit.
Fix the upstream endpoint producing oversized responses if it is unexpectedly large.
Check for runaway/looping generation inflating responses beyond intended size.

Example fix

// before: single large forwarded response
const body = await readBridgeForwardResponseBody(stream, { maxBodyBytes: 1_048_576 }, reservation);
// after: paginate or stream in bounded pieces
for await (const piece of paginatedFetch(url, { pageSize: 64 * 1024 })) {
  const body = await readBridgeForwardResponseBody(piece, { maxBodyBytes: 1_048_576 }, reservation);
  consume(body);
}

Defensive patterns

Strategy: validation

Validate before calling

const contentLength = Number(responseHeaders["content-length"] ?? 0);
if (contentLength > maxBodyBytes) throw new Error(`response of ${contentLength} bytes exceeds bridge limit ${maxBodyBytes}; use chunked download`);

Type guard

function bodyWithinLimit(size: number, maxBodyBytes: number): boolean {
  return size > 0 && size <= maxBodyBytes;
}

Try / catch

try {
  const body = await readBridgeForwardResponseBody(stream, bounds, reservation);
} catch (err) {
  if (String(err.message).includes("byte ceiling")) {
    throw new Error("response too large for bridge; paginate or raise maxBodyBytes", { cause: err });
  }
  throw err;
}

Prevention

Set maxBodyBytes above the largest legitimate forwarded response.
Use ranged/chunked downloads for large artifacts instead of one forwarded body.
Alert on endpoints whose response sizes approach the limit.
Cap agent-side request sizes before they hit the bridge.

When it happens

Trigger: readBridgeForwardResponseBody streams a response whose accumulated totalBytes exceeds maxBodyBytes; the stream is cancelled and bridgeResponseBodyLimitError(maxBodyBytes) is thrown. Happens on any forwarded HTTP response larger than the configured ceiling.

Common situations: Agent requests a large file/download through the bridge; logs or API responses unexpectedly huge; maxBodyBytes configured too low for legitimate workloads; a looping endpoint streaming unbounded data.

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

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/b151ec2a5b22e24f. Report an issue: GitHub.