{"record":{"id":"9c050b2ad4d339fc","repo":"paperclipai/paperclip","slug":"local-process-confinement-requires-bubblewrap-but","errorCode":null,"errorMessage":"Local process confinement requires Bubblewrap, but \"${requestedSandboxCommand}\" was not found in PATH. Install bwrap or configure filesystemSandboxCommand.","messagePattern":"Local process confinement requires Bubblewrap, but \"(.+?)\" was not found in PATH\\. Install bwrap or configure filesystemSandboxCommand\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/adapter-utils/src/server-utils.ts","lineNumber":2382,"sourceCode":"    return {\n      command: sshResolved,\n      args: spawnTarget.args,\n      cwd: process.cwd(),\n      cleanup: spawnTarget.cleanup,\n    };\n  }\n\n  const resolved = await resolveCommandPath(command, cwd, env);\n  const executable = resolved ?? command;\n\n  if (options.localProcessSandbox) {\n    if (!resolved) {\n      throw new Error(`Command not found in PATH: \"${command}\"`);\n    }\n    const requestedSandboxCommand = options.localProcessSandbox.command?.trim() || \"bwrap\";\n    const sandboxCommand = await resolveCommandPath(requestedSandboxCommand, cwd, env);\n    if (!sandboxCommand) {\n      throw new Error(\n        `Local process confinement requires Bubblewrap, but \"${requestedSandboxCommand}\" was not found in PATH. Install bwrap or configure filesystemSandboxCommand.`,\n      );\n    }\n    const sandboxTarget = await buildLocalProcessSandboxSpawnTarget({\n      executable,\n      args,\n      cwd,\n      options: options.localProcessSandbox,\n    });\n    return { ...sandboxTarget, command: sandboxCommand };\n  }\n\n  if (process.platform !== \"win32\") {\n    return { command: executable, args };\n  }\n\n  if (/\\.(cmd|bat)$/i.test(executable)) {\n    // Always use cmd.exe for .cmd/.bat wrappers. Some environments override","sourceCodeStart":2364,"sourceCodeEnd":2400,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/packages/adapter-utils/src/server-utils.ts#L2364-L2400","documentation":"Thrown when localProcessSandbox is enabled but the sandboxing binary (Bubblewrap by default, or options.localProcessSandbox.command) is not found in PATH. Local process confinement depends on this binary to build the sandboxed spawn target, so its absence is fatal — the orchestrator will not run the agent unsandboxed when confinement was requested.","triggerScenarios":"Calling execute/spawn with options.localProcessSandbox set while resolveCommandPath for the sandbox command (default 'bwrap', or a custom filesystemSandboxCommand) returns null.","commonSituations":"Linux distro/container without bubblewrap installed (common on minimal images, and unavailable on macOS/Windows); custom filesystemSandboxCommand points to a binary not on PATH; bwrap installed but PATH not propagated to the adapter process.","solutions":["Install bubblewrap: 'apt-get install -y bubblewrap' (or distro equivalent) on the Linux host.","Set options.localProcessSandbox.command (filesystemSandboxCommand) to the absolute path of an available sandboxer if 'bwrap' is wrong.","If confinement is not required for this environment, disable localProcessSandbox in the config.","Confirm PATH includes the directory containing bwrap when the adapter process starts."],"exampleFix":"// before\nlocalProcessSandbox: { command: 'bwrap' } // not installed\n// after — point at firejail path, or disable\nlocalProcessSandbox: { command: '/usr/bin/firejail' }","handlingStrategy":"validation","validationCode":"const sandboxCmd = localProcessSandbox.command?.trim() || 'bwrap';\nif (!(await resolveCommandPath(sandboxCmd, cwd, env))) {\n  throw new Error(`Sandbox binary '${sandboxCmd}' missing; install it or disable confinement`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install bubblewrap on Linux hosts that use localProcessSandbox.","Set filesystemSandboxCommand to an available sandboxer if bwrap is unavailable.","Disable localProcessSandbox on platforms without a supported sandboxer."],"tags":["environment","sandbox","bwrap","dependencies","configuration"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}