paperclipai/paperclip · error · Error

Failed to start sandbox ACP process session bridge

Error message

Failed to start sandbox ACP process session bridge: ${startResult.stderr || startResult.stdout}

What it means

Bridge-launch failure in sandbox ACP mode: the nohup'd node wrapper that hosts the process-session bridge failed to start (its launch command reported an error on stderr/stdout), so no ACP session can be established with the sandbox.

Solutions

1. Inspect the bridge start output in the error and fix the cause (missing deps, port conflicts).
2. Verify the sandbox image contains the ACP process session bridge binary.

When it happens

Trigger: Thrown at packages/adapter-utils/src/execution-target.ts:1567 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

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

// before it removes `sessionDir` unconditionally. The wrapper writes the
// acknowledgement right after it arms its own kill timer, well before its
// child actually exits, so this budget only needs to cover message delivery,
// not the child's full shutdown.
const DEFAULT_PROCESS_SESSION_SHUTDOWN_WAIT_MS = 3_000;

function jsonLine(value: unknown): string {
  return `${JSON.stringify(value)}\n`;
}

function splitJsonLines(buffer: string): { lines: string[]; rest: string } {
  const parts = buffer.split(/\n/);
  return { lines: parts.slice(0, -1), rest: parts.at(-1) ?? "" };
}

async function writeProcessSessionProxyScript(dir: string, port: number, token: string): Promise<string> {
  await fs.mkdir(dir, { recursive: true });
  const proxyPath = path.join(dir, PROCESS_SESSION_PROXY_SCRIPT);
  await fs.writeFile(proxyPath, getProcessSessionProxySource({ port, token }), { mode: 0o700 });
  return proxyPath;
}

// Content-hash-skip the process-session remote script write, mirroring the
// sandbox callback bridge entrypoint sha256 gate. The script is a static
// Paperclip-authored `.mjs` that only changes when the build changes, so on a
// warm start (same sandbox, script already present) the single sha-gate exec
// skips the ~3-exec base64 upload entirely. `syncRemoteTextFileWithHashSkip`
// fails loud on a check error rather than silently re-uploading.
async function syncProcessSessionRemoteScript(input: {
  runner: CommandManagedRuntimeRunner;
  remoteCwd: string;
  remoteScriptDir: string;
  remoteScriptPath: string;
  timeoutMs?: number | null;
  shellCommand?: "bash" | "sh" | null;
  outputToStdout?: boolean;
}): Promise<{ uploaded: boolean }> {

View on GitHub (pinned to 3f1d897a7c)