paperclipai/paperclip · critical · Error

Failed to start sandbox ACP process session bridge: ${startR

Error message

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

What it means

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.

Source

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

        [
          `mkdir -p ${shellQuote(stdinDir)} ${shellQuote(eventsDir)}`,
          `PAPERCLIP_PROCESS_SESSION_DIR=${shellQuote(sessionDir)} ` +
            `PAPERCLIP_PROCESS_SESSION_COMMAND_B64=${shellQuote(commandPayload)} ` +
            `nohup node ${shellQuote(remoteScriptPath)} >/dev/null 2>&1 < /dev/null &`,
          "printf '%s\\n' \"$!\"",
        ].join("\n"),
      ),
      cwd: target.remoteCwd,
      env: {
        PAPERCLIP_SANDBOX_EXEC_CHANNEL: "bridge",
      },
      timeoutMs,
      // The wrapper launch is bridge plumbing. Keep it off the persistent
      // session so it never queues behind an in-run session command.
      bypassSession: true,
    });
    if (startResult.timedOut || (startResult.exitCode ?? 1) !== 0) {
      throw new Error(`Failed to start sandbox ACP process session bridge: ${startResult.stderr || startResult.stdout}`);
    }
  }

  let socket: net.Socket | null = null;
  let stopping = false;
  let stdinSeq = 0;
  let pollTimer: NodeJS.Timeout | null = null;
  const pendingRemoteEvents: Array<{
    type?: string;
    stream?: "stdout" | "stderr";
    data?: string;
    code?: number | null;
    signal?: string | null;
    message?: string;
  }> = [];
  const token = createSandboxCallbackBridgeToken(18);
  const proxyDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-process-session-proxy-"));

View on GitHub (pinned to 67001ec6eb)

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.

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify Node.js is available in the sandbox before bridge startup
async function ensureNodeOnSandboxPath(target: AdapterSandboxExecutionTarget): Promise<void> {
  const runner = requireSandboxRunner(target);
  const result = await runner.execute({
    command: "sh",
    args: ["-c", "node --version"],
    cwd: target.remoteCwd,
    timeoutMs: target.timeoutMs ?? 15_000,
  });
  if (result.timedOut || (result.exitCode ?? 1) !== 0) {
    throw new Error("Node.js is not available in the sandbox; cannot start ACP bridge.");
  }
}

Try / catch

try {
  await startSandboxAcpProcessSessionBridge(target, input);
} catch (err) {
  if (err instanceof Error && err.message.includes("Failed to start sandbox ACP process session bridge")) {
    // The stderr/stdout in the message reveals the launch failure reason
    logger.error(`ACP bridge startup failed: ${err.message}`);
  }
  throw err;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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