paperclipai/paperclip · error · Error

Timed out while installing the adapter runtime command via:

Error message

Timed out while installing the adapter runtime command via: ${installCommand}

What it means

Thrown by ensureAdapterExecutionTargetRuntimeCommandInstalled when the install command for an adapter runtime CLI times out AND the binary is still not detectable on PATH afterward. The function first tries the install command, then if it failed or timed out, re-checks with `command -v <detectCommand>`; if that recheck also fails (or no detectCommand is configured), it throws this timeout variant.

Source

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

        env: input.env,
        timeoutSec: input.timeoutSec,
        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,
  );
}

View on GitHub (pinned to 67001ec6eb)

Solutions

Increase timeoutSec on the ensureAdapterExecutionTargetRuntimeCommandInstalled input to accommodate slow installs.
Pre-install the runtime CLI in the sandbox image so the install step is unnecessary.
Ensure the sandbox network allowlist permits egress to the package registry used by the install command.
Make the install command non-interactive (e.g. add --yes / --non-interactive flags).

Example fix

// before
await ensureAdapterExecutionTargetRuntimeCommandInstalled({
  runId,
  target,
  installCommand: "npm install -g @scope/cli",
  detectCommand: "mycli",
  cwd,
  env,
  timeoutSec: 30,
});
// after
await ensureAdapterExecutionTargetRuntimeCommandInstalled({
  runId,
  target,
  installCommand: "npm install -g @scope/cli --no-fund --no-audit",
  detectCommand: "mycli",
  cwd,
  env,
  timeoutSec: 180,
});

Defensive patterns

Strategy: validation

Validate before calling

// Validate install command and timeout before calling
function validateInstallConfig(input: { installCommand?: string | null; timeoutSec?: number; detectCommand?: string | null }): string | null {
  if (!input.installCommand?.trim()) return "installCommand is required for sandbox targets";
  if ((input.timeoutSec ?? 0) < 60) return "timeoutSec should be at least 60s for sandbox installs";
  if (!input.detectCommand?.trim()) return "detectCommand is recommended to recover from transient install failures";
  return null;
}

Try / catch

try {
  await ensureAdapterExecutionTargetRuntimeCommandInstalled(input);
} catch (err) {
  if (err instanceof Error && err.message.includes("Timed out while installing")) {
    logger.error(`Install timed out: ${err.message}. Consider pre-baking the CLI into the image.`);
  }
  throw err;
}

Prevention

Pre-install the adapter CLI in the sandbox image to eliminate runtime install entirely.
Set timeoutSec generously (120s+) for npm/pip global installs.
Ensure the sandbox network allowlist permits egress to the package registry.
Always provide a detectCommand so transient install failures can be recovered.

When it happens

Trigger: Calling ensureAdapterExecutionTargetRuntimeCommandInstalled with target.transport === 'sandbox', a non-empty installCommand, and either no detectCommand or a detectCommand that also fails the `command -v` recheck. The underlying runAdapterExecutionTargetShellCommand for installCommand returned { timedOut: true }.

Common situations: The install command runs `npm install -g` or similar against a slow/unreachable registry from inside the sandbox; the install timeoutSec is too short for large installs; the sandbox has no network egress to the package registry; the install command hangs waiting for user input.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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