can1357/oh-my-pi · error

ssh binary not found on PATH

Error message

ssh binary not found on PATH

What it means

ensureSshBinary checks for the ssh executable on PATH (via $which) before running any SSH operation and throws this error if it is absent. The library shells out to the system ssh (ControlMaster, remote commands), so a native ssh client is a hard requirement.

Source

Thrown at packages/coding-agent/src/ssh/connection-manager.ts:333

	});
	return {
		exitCode: result.exitCode,
		stdout: result.stdout.trim(),
		stderr: result.stderr.trim(),
	};
}

/**
 * Test-only surface for exercising the pre-command SSH helpers against a
 * fake `ssh` binary with a shortened timeout. External code MUST NOT depend
 * on this — call `ensureConnection` / `ensureHostInfo` instead.
 * @internal
 */
export const _sshHelpersForTests = { runSshSync, runSshCaptureSync };

function ensureSshBinary(): void {
	if (!$which("ssh")) {
		throw new Error("ssh binary not found on PATH");
	}
}

function parseOs(value: unknown): SSHHostOs | null {
	if (typeof value !== "string") return null;
	const normalized = value.trim().toLowerCase();
	switch (normalized) {
		case "windows":
			return "windows";
		case "linux":
			return "linux";
		case "macos":
		case "darwin":
			return "macos";
		case "unknown":
			return "unknown";
		default:
			return null;

View on GitHub (pinned to 9690622007)

Solutions

1. Install the client: Debian/Ubuntu `apt-get install -y openssh-client`, macOS `brew install openssh` (or it is preinstalled), Windows: Settings → Optional Features → OpenSSH Client
2. Verify `which ssh` resolves; fix PATH to include its directory
3. In Docker, use an image with openssh-client or add it to your Dockerfile
4. For GUI/cron launches, set PATH explicitly in the launch environment

Example fix

# before
$ omp ssh ...   # Error: ssh binary not found on PATH
# after (Debian/Ubuntu)
$ sudo apt-get install -y openssh-client
$ which ssh && omp ssh ...

import { $which } from "@oh-my-pi/pi-utils";
if (!$which("ssh")) {
  throw new Error("openssh client required: apt install openssh-client / brew install openssh");
}

try {
  await connect(target);
} catch (err) {
  if (err instanceof Error && err.message === "ssh binary not found on PATH") {
    console.error("Install OpenSSH client and ensure it is on PATH:", process.env.PATH);
  }
  throw err;
}

When it happens

Trigger: Any SSH connection/ssh:// operation on a machine without OpenSSH client installed or with a PATH that omits its location.

Common situations: Minimal Docker images (no openssh-client), Windows without the optional OpenSSH feature, stripped-down CI runners, running under an environment where PATH was sanitized (GUI-launched apps, cron).

Related errors

• ${displayName} executable not found on PATH
• imageUrls exposure "${name}" requires the ${name} binary on
• ssh binary not found in PATH
• Could not resolve ${APP_NAME} binary path in PATH
• ${availability.reason ?? "Julia kernel unavailable"}

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/7372af1ab766aed4. Report an issue: GitHub.