paperclipai/paperclip · error · Error

Local process confinement requires Bubblewrap, but "${reques

Error message

Local process confinement requires Bubblewrap, but "${requestedSandboxCommand}" was not found in PATH. Install bwrap or configure filesystemSandboxCommand.

What it means

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.

Source

Thrown at packages/adapter-utils/src/server-utils.ts:2382

    return {
      command: sshResolved,
      args: spawnTarget.args,
      cwd: process.cwd(),
      cleanup: spawnTarget.cleanup,
    };
  }

  const resolved = await resolveCommandPath(command, cwd, env);
  const executable = resolved ?? command;

  if (options.localProcessSandbox) {
    if (!resolved) {
      throw new Error(`Command not found in PATH: "${command}"`);
    }
    const requestedSandboxCommand = options.localProcessSandbox.command?.trim() || "bwrap";
    const sandboxCommand = await resolveCommandPath(requestedSandboxCommand, cwd, env);
    if (!sandboxCommand) {
      throw new Error(
        `Local process confinement requires Bubblewrap, but "${requestedSandboxCommand}" was not found in PATH. Install bwrap or configure filesystemSandboxCommand.`,
      );
    }
    const sandboxTarget = await buildLocalProcessSandboxSpawnTarget({
      executable,
      args,
      cwd,
      options: options.localProcessSandbox,
    });
    return { ...sandboxTarget, command: sandboxCommand };
  }

  if (process.platform !== "win32") {
    return { command: executable, args };
  }

  if (/\.(cmd|bat)$/i.test(executable)) {
    // Always use cmd.exe for .cmd/.bat wrappers. Some environments override

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Install bubblewrap: 'apt-get install -y bubblewrap' (or distro equivalent) on the Linux host.
2. Set options.localProcessSandbox.command (filesystemSandboxCommand) to the absolute path of an available sandboxer if 'bwrap' is wrong.
3. If confinement is not required for this environment, disable localProcessSandbox in the config.
4. Confirm PATH includes the directory containing bwrap when the adapter process starts.

Example fix

// before
localProcessSandbox: { command: 'bwrap' } // not installed
// after — point at firejail path, or disable
localProcessSandbox: { command: '/usr/bin/firejail' }

const sandboxCmd = localProcessSandbox.command?.trim() || 'bwrap';
if (!(await resolveCommandPath(sandboxCmd, cwd, env))) {
  throw new Error(`Sandbox binary '${sandboxCmd}' missing; install it or disable confinement`);
}

When it happens

Trigger: Calling execute/spawn with options.localProcessSandbox set while resolveCommandPath for the sandbox command (default 'bwrap', or a custom filesystemSandboxCommand) returns null.

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

Related errors

• Command not found in PATH: "${command}"
• Paperclip sandbox proxy socket path is ${pathBytes} bytes, e
• Unable to create a Linux-safe Paperclip sandbox proxy socket
• Local process filesystem and network scopes are currently su
• prepareSandboxManagedRuntime requires a client that exposes

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