paperclipai/paperclip · warning

SSH fixture prerequisites are incomplete: ${status.ssh.reaso

Error message

SSH fixture prerequisites are incomplete: ${status.ssh.reason ?? "unknown reason"}

What it means

env-lab doctor calls getSshEnvLabSupport() (packages/adapter-utils/src/ssh.ts), which checks platform policy and required commands. supported=false happens when: the platform is macOS without PAPERCLIP_ENABLE_DARWIN_SSH_ENV_LAB=1 (fixture disabled there by default), or one of ssh/sshd/ssh-keygen is not on PATH (reason: 'Missing required command: <cmd>'). The doctor prints the reason so you know exactly which prerequisite is missing.

Source

Thrown at cli/src/commands/env-lab.ts:196

  parts.push(shellQuoteArgument(invocation.entry), "env-lab down");
  if (opts.instance !== undefined) {
    parts.push("--instance", shellQuoteArgument(opts.instance));
  }
  return parts.join(" ");
}

export async function envLabDoctorCommand(opts: { instance?: string; json?: boolean }) {
  const status = await collectEnvLabDoctorStatus(opts);

  if (opts.json) {
    printJson(status);
    return;
  }

  if (status.ssh.supported) {
    p.log.success("SSH fixture prerequisites are installed.");
  } else {
    p.log.warn(`SSH fixture prerequisites are incomplete: ${status.ssh.reason ?? "unknown reason"}`);
  }

  if (status.ssh.state && status.ssh.running) {
    p.log.success("SSH env-lab fixture is running.");
    summarizeFixture(status.ssh.state);
    p.log.message(`Private key: ${pc.dim(status.ssh.state.clientPrivateKeyPath)}`);
    p.log.message(`Known hosts: ${pc.dim(status.ssh.state.knownHostsPath)}`);
  } else if (status.ssh.state) {
    p.log.warn("SSH env-lab fixture state exists, but the process is not running.");
    p.log.message(`State: ${pc.dim(status.statePath)}`);
  } else {
    p.log.info("SSH env-lab fixture is not running.");
    p.log.message(`State: ${pc.dim(status.statePath)}`);
  }

  // The cleanup hint runs the same CLI that prints it, so it stops the correct
  // version. The bundled build runs `dist/index.js`; a source checkout runs
  // `src/index.ts` through the checked-out tsx runner. The hint uses absolute

View on GitHub (pinned to 120ae5428f)

Solutions

  1. Install the missing binaries: apt-get install -y openssh-client openssh-server (or apk/yum equivalents) so ssh, sshd and ssh-keygen are all on PATH.
  2. On macOS, opt in explicitly: export PAPERCLIP_ENABLE_DARWIN_SSH_ENV_LAB=1 before running env-lab commands.
  3. Re-run `paperclipai env-lab doctor` and confirm it now prints 'SSH fixture prerequisites are installed.'
  4. Use `paperclipai env-lab doctor --json` to capture the exact reason string in scripts.

Example fix

# before
$ paperclipai env-lab doctor
! SSH fixture prerequisites are incomplete: Missing required command: sshd

# after
$ sudo apt-get install -y openssh-server openssh-client
$ paperclipai env-lab doctor
√ SSH fixture prerequisites are installed.
Defensive patterns

Strategy: validation

Validate before calling

import { execFileSync } from "node:child_process";
const required = ["ssh", "sshd", "ssh-keygen"];
const missing = required.filter((c) => {
  try { execFileSync("which", [c], { stdio: "ignore" }); return false; } catch { return true; }
});
if (missing.length > 0) throw new Error(`Install openssh first; missing: ${missing.join(", ")}`);

Prevention

When it happens

Trigger: Running `paperclipai env-lab doctor` on macOS without the opt-in env var; on a slim Docker image or minimal Linux that lacks openssh client/server binaries.

Common situations: CI containers without openssh-server; dev machines where only the ssh client is installed; macOS users hitting the default-off fixture gate.

Related errors

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/c53b186f719ae111. Report an issue: GitHub.