can1357/oh-my-pi · error · Error

harbor not found on PATH. Install with: uv tool install harb

Error message

harbor not found on PATH. Install with: uv tool install harbor

What it means

runBenchmark() requires the `harbor` CLI to be available on PATH before starting any benchmark run. If `which('harbor')` finds nothing, it throws immediately with the exact install command. This is an upfront environment check so runs fail fast instead of mid-benchmark.

Source

Thrown at packages/metaharness/src/runner.ts:1543

	}
}

// ──────────────────────────────────────────────────────────────────────── main

interface BenchmarkRun {
	exitCode: number;
	jobName: string;
	jobDir: string;
	benchDir: string;
	tarball: string | null;
	elapsedMs: number;
	totals: Totals | null;
	reportPath: string | null;
}

async function runBenchmark(cfg: Config): Promise<BenchmarkRun> {
	if (!which("harbor")) {
		throw new Error("harbor not found on PATH. Install with: uv tool install harbor");
	}
	if (cfg.agent === "omp" && cfg.envType === "docker" && !which("docker")) {
		throw new Error("docker not found on PATH (required to run task containers).");
	}
	if (cfg.envType === "apple-container" && !which("container")) {
		throw new Error(
			"Apple 'container' CLI not found. Install with: brew install container && container system start",
		);
	}

	const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
	const modelSlug = (cfg.models[0] ?? "model").replace(/[^a-zA-Z0-9]+/g, "-");
	const jobName = cfg.jobName ?? `${modelSlug}-${stamp}`;
	const jobDir = path.join(cfg.jobsDir, jobName);
	const benchDir = path.join(cfg.jobsDir, "_bench", jobName);
	fs.mkdirSync(benchDir, { recursive: true });
	if (!cfg.resume && !cfg.dryRun) {
		// Snapshot the resolved launch config so a later `--resume <job>` can

View on GitHub (pinned to 9690622007)

Solutions

Install harbor: `uv tool install harbor`
Verify with `which harbor` / `harbor --version` in the same shell that runs the harness
If already installed, ensure uv's tool bin dir (`uv tool update-shell` or ~/.local/bin) is on PATH
In CI, add a setup step that installs harbor before the benchmark job

Example fix

// before
$ omp benchmark ...
harbor not found on PATH. Install with: uv tool install harbor
// after
$ uv tool install harbor
$ harbor --version

Defensive patterns

Strategy: validation

Validate before calling

import { spawnSync } from "node:child_process";
if (spawnSync("which", ["harbor"]).status !== 0) {
  throw new Error("Install harbor first: uv tool install harbor");
}

Try / catch

try {
  await runBenchmark(cfg);
} catch (err) {
  if (err instanceof Error && err.message.includes("harbor not found on PATH")) {
    console.error("Run: uv tool install harbor, then ensure uv's bin dir is on PATH.");
  } else throw err;
}

Prevention

Install harbor via `uv tool install harbor` on every dev machine and CI image
Run `uv tool update-shell` so uv's tool bin dir is on PATH permanently
Pin harbor in CI setup steps before benchmark jobs
Verify with `which harbor` in the exact shell/profile that launches the harness

When it happens

Trigger: Running the benchmark harness (`runBenchmark`) in an environment where harbor was never installed, was installed into a non-PATH location (e.g. inside a venv), or was installed with a different tool manager afterward.

Common situations: Fresh machine or CI container without harbor; harbor installed via pip into a venv that isn't activated so `uv tool install harbor`'s shim isn't on PATH; PATH differences between the shell and the process spawning the harness.

Related errors

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