paperclipai/paperclip · error · Error

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

Error message

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

What it means

Thrown by ensureAdapterExecutionTargetRuntimeCommandInstalled when the install command exits with a non-zero code (not a timeout) AND the binary is still not found on PATH. This is the non-timeout counterpart to error 303: the install ran to completion but failed, and the detect-command recheck could not rescue it.

Source

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

        graceSec: input.graceSec,
      },
    );
    if (!recheck.timedOut && recheck.exitCode === 0) {
      if (input.onLog) {
        const reason = result.timedOut ? "timed out" : `exited ${result.exitCode ?? "?"}`;
        await input.onLog(
          "stderr",
          `[paperclip] Install command ${reason} (${installCommand}) but ${detectCommand} is on PATH; continuing.\n`,
        );
      }
      return;
    }
  }

  if (result.timedOut) {
    throw new Error(`Timed out while installing the adapter runtime command via: ${installCommand}`);
  }
  throw new Error(`Failed to install the adapter runtime command via: ${installCommand}`);
}

export async function ensureAdapterExecutionTargetFile(
  runId: string,
  target: AdapterExecutionTarget | null | undefined,
  filePath: string,
  options: AdapterExecutionTargetShellOptions,
): Promise<void> {
  await runAdapterExecutionTargetShellCommand(
    runId,
    target,
    `mkdir -p ${shellQuote(path.posix.dirname(filePath))} && : > ${shellQuote(filePath)}`,
    options,
  );
}

/**
 * Ensure a working directory exists (and is a directory) on the execution target.

View on GitHub (pinned to 67001ec6eb)

Solutions

Inspect the stderr/stdout from the install command (logged via onLog) to find the specific install failure reason.
Pre-install the runtime CLI in the sandbox image to avoid runtime install failures entirely.
Fix the install command to handle the sandbox environment (e.g. use --prefix for a writable directory, add missing build tools).
Verify the package name and version in the install command are correct and published.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await ensureAdapterExecutionTargetRuntimeCommandInstalled(input);
} catch (err) {
  if (err instanceof Error && err.message.includes("Failed to install the adapter runtime command")) {
    // The install command exited non-zero — inspect onLog output for details
    throw new Error(`Adapter runtime install failed. Command: ${input.installCommand}. Check logs for details.`);
  }
  throw err;
}

Prevention

Use an onLog callback to capture install command stderr/stdout for diagnosis.
Ensure the sandbox image has the build dependencies the install command needs.
Verify the package name and version in the install command are correct and accessible.

When it happens

Trigger: Calling ensureAdapterExecutionTargetRuntimeCommandInstalled with target.transport === 'sandbox'. The install command returned { timedOut: false, exitCode: non-zero }. Then either no detectCommand is set, or `command -v <detectCommand>` returned non-zero.

Common situations: The install command fails due to missing build dependencies in the sandbox image; the package version does not exist or has a broken transitive dependency; the install command lacks permissions to write to the global install directory; the sandbox filesystem is read-only.

Related errors

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