paperclipai/paperclip · error · Error

Bridge server did not expose a TCP address.

Error message

Bridge server did not expose a TCP address.

What it means

Thrown by the sandbox callback bridge server startup. Fires after server.listen when server.address() returns null or a pipe/string instead of a TCP address object, meaning the OS did not give the bridge a bound TCP endpoint to publish in ready.json.

Source

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

// A crashed gateway is a dead loopback port for the rest of the run: nothing
// inside the sandbox respawns this process, and every later agent API call
// then fails at the connection level. Once the gateway is ready, log an
// uncaught fault to stderr (the host redirects it into logs/bridge.log) and
// keep serving — the relay holds no state a fault can corrupt beyond the one
// request it interrupted. Before readiness the same fault means the gateway
// can never become usable (a failed bind, a failed readiness write), so exit
// instead: surviving there only leaves an un-ready zombie behind while the
// host waits out its readiness poll.
let gatewayReady = false;
process.on("uncaughtException", (error) => {
  process.stderr.write(
    "[paperclip-bridge] uncaught exception: " + (error && error.stack ? error.stack : String(error)) + "\\n",
  );
  if (!gatewayReady) {
    process.exit(1);
  }
});
process.on("unhandledRejection", (reason) => {
  const detail = reason && typeof reason === "object" && "stack" in reason ? reason.stack : String(reason);
  process.stderr.write("[paperclip-bridge] unhandled rejection: " + detail + "\\n");
  if (!gatewayReady) {
    process.exit(1);
  }
});

// The embedded zero-dependency frame codec. The duplex gateway uses it; the file
// gateway ignores it.
${DUPLEX_GATEWAY_CODEC_SOURCE}

// The embedded zero-dependency process body-byte ledger. Both gateway modes
// use it: readBodyBytes reserves against it, and each mode's request
// handler releases what it reserved once the body is no longer needed.
${BRIDGE_PROCESS_BODY_LEDGER_SOURCE}

// The multiplier matches HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS (4) in

View on GitHub (pinned to 01ad858492)

Solutions

1. Check the bridge server configuration so it binds a TCP address, and retry.

When it happens

Trigger: Thrown at packages/adapter-utils/src/sandbox-callback-bridge.ts:1880 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/db29f27116ad888e. Report an issue: GitHub.