{"record":{"id":"c83986bfaf6805f1","repo":"paperclipai/paperclip","slug":"failed-to-start-sandbox-acp-process-session-bridge","errorCode":null,"errorMessage":"Failed to start sandbox ACP process session bridge: ${startResult.stderr || startResult.stdout}","messagePattern":"Failed to start sandbox ACP process session bridge: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/adapter-utils/src/execution-target.ts","lineNumber":1511,"sourceCode":"        [\n          `mkdir -p ${shellQuote(stdinDir)} ${shellQuote(eventsDir)}`,\n          `PAPERCLIP_PROCESS_SESSION_DIR=${shellQuote(sessionDir)} ` +\n            `PAPERCLIP_PROCESS_SESSION_COMMAND_B64=${shellQuote(commandPayload)} ` +\n            `nohup node ${shellQuote(remoteScriptPath)} >/dev/null 2>&1 < /dev/null &`,\n          \"printf '%s\\\\n' \\\"$!\\\"\",\n        ].join(\"\\n\"),\n      ),\n      cwd: target.remoteCwd,\n      env: {\n        PAPERCLIP_SANDBOX_EXEC_CHANNEL: \"bridge\",\n      },\n      timeoutMs,\n      // The wrapper launch is bridge plumbing. Keep it off the persistent\n      // session so it never queues behind an in-run session command.\n      bypassSession: true,\n    });\n    if (startResult.timedOut || (startResult.exitCode ?? 1) !== 0) {\n      throw new Error(`Failed to start sandbox ACP process session bridge: ${startResult.stderr || startResult.stdout}`);\n    }\n  }\n\n  let socket: net.Socket | null = null;\n  let stopping = false;\n  let stdinSeq = 0;\n  let pollTimer: NodeJS.Timeout | null = null;\n  const pendingRemoteEvents: Array<{\n    type?: string;\n    stream?: \"stdout\" | \"stderr\";\n    data?: string;\n    code?: number | null;\n    signal?: string | null;\n    message?: string;\n  }> = [];\n  const token = createSandboxCallbackBridgeToken(18);\n  const proxyDir = await fs.mkdtemp(path.join(os.tmpdir(), \"paperclip-process-session-proxy-\"));\n","sourceCodeStart":1493,"sourceCodeEnd":1529,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/packages/adapter-utils/src/execution-target.ts#L1493-L1529","documentation":"Thrown during the legacy (non-streamed) sandbox ACP process session bridge startup when the `nohup node <remoteScript>` wrapper launch via the sandbox runner times out or exits non-zero. This is the bridge plumbing step that backgrounds the process-session wrapper inside the sandbox; failure here means the sandbox could not start the bridge process that mediates long-running agent sessions.","triggerScenarios":"Starting a sandbox ACP process session with streamOutput=false (legacy poll path). The runner.execute call that launches the combined `mkdir -p` + `nohup node <script> &` wrapper returns { timedOut: true } or { exitCode: non-zero }. The stderr/stdout from the failed launch is included in the message.","commonSituations":"Node.js is not installed or not on PATH in the sandbox image; the remote script path is wrong or the script file was not synced; the sandbox lacks resources to spawn the node process; the PAPERCLIP_SANDBOX_EXEC_CHANNEL env or session dir setup is malformed; the sandbox lease expired during bridge startup.","solutions":["Ensure Node.js is installed and on PATH inside the sandbox image.","Check the stderr/stdout detail in the error message for the specific failure (e.g. 'node: not found', permission denied).","Verify the syncProcessSessionRemoteScript step succeeded before the launch.","Switch to the streamed path (streamOutput=true) if the legacy poll path is unreliable for your sandbox provider."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Verify Node.js is available in the sandbox before bridge startup\nasync function ensureNodeOnSandboxPath(target: AdapterSandboxExecutionTarget): Promise<void> {\n  const runner = requireSandboxRunner(target);\n  const result = await runner.execute({\n    command: \"sh\",\n    args: [\"-c\", \"node --version\"],\n    cwd: target.remoteCwd,\n    timeoutMs: target.timeoutMs ?? 15_000,\n  });\n  if (result.timedOut || (result.exitCode ?? 1) !== 0) {\n    throw new Error(\"Node.js is not available in the sandbox; cannot start ACP bridge.\");\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await startSandboxAcpProcessSessionBridge(target, input);\n} catch (err) {\n  if (err instanceof Error && err.message.includes(\"Failed to start sandbox ACP process session bridge\")) {\n    // The stderr/stdout in the message reveals the launch failure reason\n    logger.error(`ACP bridge startup failed: ${err.message}`);\n  }\n  throw err;\n}","preventionTips":["Ensure Node.js is installed in the sandbox image.","Verify the remote bridge script was synced before the launch step.","Use streamOutput=true for the streamed path if the legacy poll path is unreliable."],"tags":["sandbox","bridge","process-session","execution-target","adapter-utils"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}