{"record":{"id":"f01295cc5a507898","repo":"paperclipai/paperclip","slug":"command-not-found-in-path-ssh","errorCode":null,"errorMessage":"Command not found in PATH: \"ssh\"","messagePattern":"Command not found in PATH: \"ssh\"","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/adapter-utils/src/server-utils.ts","lineNumber":2354,"sourceCode":"  return path.join(fallbackRoot, \"System32\", \"cmd.exe\");\n}\n\nasync function resolveSpawnTarget(\n  command: string,\n  args: string[],\n  cwd: string,\n  env: NodeJS.ProcessEnv,\n  options: {\n    remoteExecution?: RemoteExecutionSpec | null;\n    remoteEnv?: Record<string, string> | null;\n    localProcessSandbox?: LocalProcessSandboxOptions | null;\n  } = {},\n): Promise<SpawnTarget> {\n  const remote = options.remoteExecution ?? null;\n  if (remote) {\n    const sshResolved = await resolveCommandPath(\"ssh\", process.cwd(), env);\n    if (!sshResolved) {\n      throw new Error('Command not found in PATH: \"ssh\"');\n    }\n    const spawnTarget = await buildSshSpawnTarget({\n      spec: remote,\n      command,\n      args,\n      env: Object.fromEntries(\n        Object.entries(options.remoteEnv ?? {}).filter((entry): entry is [string, string] => typeof entry[1] === \"string\"),\n      ),\n    });\n    return {\n      command: sshResolved,\n      args: spawnTarget.args,\n      cwd: process.cwd(),\n      cleanup: spawnTarget.cleanup,\n    };\n  }\n\n  const resolved = await resolveCommandPath(command, cwd, env);","sourceCodeStart":2336,"sourceCodeEnd":2372,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/packages/adapter-utils/src/server-utils.ts#L2336-L2372","documentation":"Thrown by the spawn-target resolver when a remoteExecution spec is configured but the local `ssh` binary cannot be found in PATH (resolveCommandPath returned null). Remote runs require a local ssh client to connect to the sandbox host; without it the adapter cannot build an SSH spawn target and fails fast.","triggerScenarios":"Calling the spawn/execute path with options.remoteExecution set, on a machine whose PATH does not contain an ssh executable. resolveCommandPath('ssh', cwd, env) returns null and the error is raised before any SSH connection attempt.","commonSituations":"Minimal container/CI image without openssh-client installed; PATH env stripped when spawning the adapter process; Windows host without OpenSSH in PATH; a sandboxed runtime that intentionally omits ssh.","solutions":["Install an ssh client (e.g. 'apt-get install -y openssh-client') in the runtime image.","Ensure PATH passed to the adapter includes the directory containing ssh (often /usr/bin).","If you did not intend remote execution, clear the remoteExecution option / config so it runs locally.","On Windows, enable the OpenSSH optional feature or add its install dir to PATH."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"import { commandExists } from './path-helpers';\nif (remoteExecution && !(await commandExists('ssh', env))) {\n  throw new Error('ssh client required for remoteExecution but not found in PATH');\n}","typeGuard":null,"tryCatchPattern":"try { await resolveCommandPath('ssh', cwd, env); } catch { /* resolveCommandPath returns null, doesn't throw */ }","preventionTips":["Include openssh-client in adapter runtime images.","Smoke-test ssh presence at startup when remoteExecution is configured.","Keep PATH intact when spawning the adapter process."],"tags":["environment","ssh","remote-execution","path","dependencies"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}