paperclipai/paperclip · error · Error

Failed to install the adapter runtime command via

Error message

Failed to install the adapter runtime command via: ${installCommand}

What it means

Install failure for adapter runtime bootstrapping: the configured install command exited non-zero (and the binary is still not on PATH), so the sandbox has no runnable adapter CLI; the install command itself is named in the message.

Solutions

  1. Run the install command manually in the sandbox to see the failure: ${installCommand}.
  2. Fix the install command or use a sandbox image with the runtime preinstalled.
Defensive patterns

Strategy: retry

When it happens

Trigger: Thrown at packages/adapter-utils/src/execution-target.ts:996 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-08-18). Data as JSON: /api/errors/01f524ae93b6a48e. Report an issue: GitHub.

Appendix: source

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

  detail?: string;
  hint?: string;
}

// Best-effort run of an adapter-supplied install command on a sandbox target
// before the resolvability + hello probe. Returns null for non-sandbox
// targets so callers can no-op. Returns a structured check otherwise — never
// throws — so the rest of the test still runs and reports the post-install
// state honestly. Caller pushes the check into its result array; the test
// report shows whether install was attempted and what came back.
export async function maybeRunSandboxInstallCommand(input: {
  runId: string;
  target: AdapterExecutionTarget | null | undefined;
  adapterKey: string;
  installCommand: string;
  /** When provided, skip the install if `command -v <detectCommand>` succeeds. */
  detectCommand?: string | null;
  env?: Record<string, string>;
  timeoutSec?: number;
}): Promise<AdapterSandboxInstallCommandCheck | null> {
  const { target, adapterKey, installCommand } = input;
  if (!target || target.kind !== "remote" || target.transport !== "sandbox") {
    return null;
  }
  const trimmed = installCommand.trim();
  if (trimmed.length === 0) return null;

  const code = `${adapterKey}_install_command_run`;

  // Skip install when the binary is already on PATH. Avoids running
  // network-dependent installers (e.g. `curl ... | bash`) on every test
  // probe when the CLI is preinstalled on the lease/template.
  const detectCommand = input.detectCommand?.trim();
  if (detectCommand) {
    try {
      const probe = await runAdapterExecutionTargetShellCommand(
        input.runId,

View on GitHub (pinned to 3f1d897a7c)