paperclipai/paperclip · error · Error

Command "${command}" is not installed or not on PATH in the

Error message

Command "${command}" is not installed or not on PATH in the sandbox environment${installDetail}.${probeStderr}

What it means

Thrown by ensureSandboxCommandResolvable as the final fallthrough: the command is not resolvable on PATH and did not time out. This is the honest 'binary is genuinely missing' error. If an install command was attempted and failed, the installFailureDetail is appended so the developer can see why the install did not fix the problem.

Source

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

      } else if ((installResult.exitCode ?? 0) !== 0) {
        const tail = (text: string) =>
          text.split(/\r?\n/).filter((line) => line.trim().length > 0).slice(-2).join(" | ").slice(0, 240);
        const reason = tail(installResult.stderr || installResult.stdout) || `exit ${installResult.exitCode ?? "?"}`;
        installFailureDetail = `install command exited ${installResult.exitCode ?? "?"}: ${reason}`;
      }
    } catch (err) {
      installFailureDetail = `install command threw: ${err instanceof Error ? err.message : String(err)}`;
    }
    probe = await probeSandboxCommandResolvable(command, target);
    if (probe.resolved) return;
    if (probe.timedOut) {
      throw new Error(`Timed out checking command "${command}" on sandbox target.`);
    }
  }

  const probeStderr = probe.stderr.length > 0 ? ` probe stderr: ${probe.stderr}` : "";
  const installDetail = installFailureDetail ? `; ${installFailureDetail}` : "";
  throw new Error(
    `Command "${command}" is not installed or not on PATH in the sandbox environment${installDetail}.${probeStderr}`,
  );
}

export async function resolveAdapterExecutionTargetCommandForLogs(
  command: string,
  target: AdapterExecutionTarget | null | undefined,
  cwd: string,
  env: NodeJS.ProcessEnv,
): Promise<string> {
  if (target?.kind === "remote" && target.transport === "sandbox") {
    return `sandbox://${target.providerKey ?? "provider"}/${target.leaseId ?? "lease"}/${target.remoteCwd} :: ${command}`;
  }
  return await resolveCommandForLogs(command, cwd, env, {
    remoteExecution: adapterExecutionTargetToRemoteSpec(target),
  });
}

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Bake the CLI binary into the sandbox image so it is on PATH at lease start, eliminating the need for an install command.
2. If using an install command, verify it installs the binary to a directory on the sandbox's PATH and that the login profile sources correctly.
3. Check the appended installFailureDetail for the specific exit code or error message and address that root cause.
4. Verify the command name passed to ensureSandboxCommandResolvable matches the binary name the install command produces.

// Pre-probe before calling ensureSandboxCommandResolvable
async function isCommandOnSandboxPath(command: string, target: AdapterSandboxExecutionTarget): Promise<boolean> {
  const probe = await probeSandboxCommandResolvable(command, target);
  return probe.resolved;
}

try {
  await ensureSandboxCommandResolvable(command, target, installCommand, timeoutSec);
} catch (err) {
  if (err instanceof Error && err.message.includes("not installed or not on PATH")) {
    // Surface a user-friendly message about the missing CLI
    throw new Error(`Adapter CLI '${command}' is missing in the sandbox. Check the image or install command.`);
  }
  throw err;
}

When it happens

Trigger: ensureSandboxCommandResolvable(command, target, installCommand, timeoutSec) where probeSandboxCommandResolvable returned { resolved: false, timedOut: false }. The install command either was not provided, ran but exited non-zero, or threw — all captured into installFailureDetail.

Common situations: The CLI binary was never baked into the sandbox image and no install command was configured; the install command points to a private registry that is unreachable from the sandbox; the install command installed to a PATH location not covered by the sandbox's login profile; the binary name in the adapter config does not match what the install command places on PATH.

Related errors

• Timed out while installing the adapter runtime command via:
• Failed to install the adapter runtime command via: ${install
• Timed out checking command "${command}" on sandbox target.
• Failed to start sandbox ACP process session bridge: ${startR
• Sandbox bridge mode requires a host-side Paperclip API token

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