paperclipai/paperclip · error · Error

PAPERCLIP_BRIDGE_QUEUE_DIR and PAPERCLIP_BRIDGE_TOKEN are re

Error message

PAPERCLIP_BRIDGE_QUEUE_DIR and PAPERCLIP_BRIDGE_TOKEN are required.

What it means

The sandbox callback bridge startup found PAPERCLIP_BRIDGE_QUEUE_DIR or PAPERCLIP_BRIDGE_TOKEN unset; both environment variables are mandatory for the bridge to exchange queued requests with the host.

Source

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

      responseHeaders = {};
      for (const [key, value] of Object.entries(headers)) {
        if (key.startsWith(":") || value == null) continue;
        responseHeaders[key] = Array.isArray(value) ? value.join(", ") : String(value);
      }
    });
    stream.on("data", (chunk: Buffer) => chunks.push(chunk));
    stream.once("end", () => settle(() => resolve({ status, headers: responseHeaders, body: Buffer.concat(chunks) })));
    stream.once("error", (error) =>
      settle(() => reject(error instanceof Error ? error : new Error(String(error)))),
    );
    stream.once("aborted", () => settle(() => reject(new Error("Bridge HTTP/2 stream aborted."))));
    if (request.body.length > 0) {
      stream.end(request.body);
    } else if (!stream.writableEnded) {
      stream.end();
    }
  });
}

/**
 * Create the sandbox HTTP/2 client gateway. It opens one HTTP/2 client
 * session on the transport `createConnection` returns, and forwards each
 * local request the caller hands it (already checked against the bridge
 * token — see {@link SandboxHttp2BridgeGatewayRequest.receivedToken}) as one
 * HTTP/2 stream. It keeps the header allowlist on the sandbox side, exactly
 * as the file-mode gateway does.
 */
export function createSandboxHttp2BridgeGateway(
  options: CreateSandboxHttp2BridgeGatewayOptions,
): SandboxHttp2BridgeGateway {
  const authority = options.authority?.trim() || SANDBOX_HTTP2_GATEWAY_DEFAULT_AUTHORITY;
  const headerAllowlist = options.headerAllowlist ?? DEFAULT_SANDBOX_CALLBACK_BRIDGE_HEADER_ALLOWLIST;
  const session = http2.connect(`http://${authority}`, {
    createConnection: options.createConnection,
  });
  // A session-level fault fails every in-flight `forwardRequest` call through

View on GitHub (pinned to 01ad858492)

Solutions

1. Set PAPERCLIP_BRIDGE_QUEUE_DIR and PAPERCLIP_BRIDGE_TOKEN in the sandbox environment.

When it happens

Trigger: Thrown at packages/adapter-utils/src/sandbox-callback-bridge.ts:1730 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-21). Data as JSON: /api/errors/2bb04a1c0d365d54. Report an issue: GitHub.