can1357/oh-my-pi · error · Error

docker not found on PATH (required to run task containers).

Error message

docker not found on PATH (required to run task containers).

What it means

When the benchmark agent is 'omp' and the environment type is 'docker', runBenchmark() requires the `docker` CLI because task containers are run through Docker. If `which('docker')` finds nothing it throws this message before the run starts. It is a preflight check guaranteeing the container runtime the selected envType needs is present.

Source

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

// ──────────────────────────────────────────────────────────────────────── 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
		// rebuild the exact same invocation without re-specifying flags.
		fs.writeFileSync(path.join(benchDir, "runner-config.json"), JSON.stringify({ ...cfg, jobName }, null, "\t"));
	}

View on GitHub (pinned to 9690622007)

Solutions

Install Docker (Docker Desktop, or `apt-get install docker-cli` / engine for your distro)
Verify with `which docker` and `docker ps` in the launching shell
If you meant a different backend, select the matching envType (e.g. apple-container) instead of docker
Fix PATH so the docker binary's directory is included for the process running the harness

Example fix

// before
$ omp benchmark --env docker ...
docker not found on PATH (required to run task containers).
// after
$ which docker || brew install --cask docker  # then start Docker Desktop
$ omp benchmark --env docker ...

Defensive patterns

Strategy: validation

Validate before calling

import { spawnSync } from "node:child_process";
if (cfg.agent === "omp" && cfg.envType === "docker" && spawnSync("which", ["docker"]).status !== 0) {
  throw new Error("Install Docker before running docker-env benchmarks");
}

Try / catch

try {
  await runBenchmark(cfg);
} catch (err) {
  if (err instanceof Error && err.message.includes("docker not found on PATH")) {
    console.error("Install Docker Desktop or docker-cli, start the daemon, and retry.");
  } else throw err;
}

Prevention

Install the docker CLI (Docker Desktop or distro package) before running docker-env benchmarks
Preflight `which docker && docker ps` in CI before the job
Use a CI image that includes the docker CLI (or docker-in-docker sidecar)
Keep Docker Desktop's bin directory on PATH (default /usr/local/bin)

When it happens

Trigger: Starting a benchmark with `--env docker` (or the equivalent Config with envType 'docker' and agent 'omp') on a machine without the docker CLI, or where docker exists only in another user's/venv PATH.

Common situations: Docker Desktop uninstalled or never installed; running inside a slim CI image without the docker CLI; using podman only (no `docker` shim); PATH not including /usr/local/bin or Docker Desktop's bin dir.

Related errors

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