What causes "docker not found on PATH (required for cleanup)." in can1357/oh-my-pi?

Install Docker (Docker Desktop on macOS, Docker Engine on Linux) so `docker` is on PATH

can1357/oh-my-pi · error · Error

docker not found on PATH (required for cleanup).

Error message

docker not found on PATH (required for cleanup).

What it means

The runner's explicit 'cleanup' subcommand requires the docker CLI to inspect and remove benchmark containers/volumes. It checks for docker before doing anything and throws immediately if the binary is missing, since cleanup cannot safely proceed without it.

Source

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

		`${bold(`${st.cfg.dataset} complete`)} — ${green(`${totals.pass}/${totals.done} passed (${successPct.toFixed(1)}%)`)}\n`,
	);
	process.stdout.write(
		`fail ${totals.fail} · error ${totals.error} · spend ${fmtUsd(totals.costUsd)} · elapsed ${fmtDur(elapsedMs)}\n`,
	);
	process.stdout.write(
		`tokens: in ${fmtNum(totals.tokIn)} · out ${fmtNum(totals.tokOut)} · cache ${fmtNum(totals.tokCache)}\n`,
	);
	process.stdout.write(`${dim("report:")} ${reportPath}\n`);
	process.stdout.write(`${dim("logs:  ")} ${logPath}\n`);
	process.stdout.write(`${dim("trials:")} ${jobDir}\n`);
	if (exitCode !== 0) process.stdout.write(yellow(`harbor exited ${exitCode}; see harbor.log\n`));
	return { exitCode, jobName, jobDir, benchDir, tarball, elapsedMs, totals, reportPath };
}

async function main(): Promise<void> {
	const argv = process.argv.slice(2);
	if (argv[0] === "cleanup") {
		if (!which("docker")) throw new Error("docker not found on PATH (required for cleanup).");
		runDockerCleanup(true);
		return;
	}
	let cfg = parseArgs(argv);
	if (cfg.resume) cfg = resolveResumeConfig(cfg);
	const exitCode = (await runBenchmark(cfg)).exitCode;
	process.exit(exitCode);
}

if (import.meta.main) {
	main().catch((err: unknown) => {
		if (isTTY) process.stdout.write(`${ESC}?25h${ESC}?1049l`);
		process.stderr.write(red(`\nerror: ${err instanceof Error ? err.message : String(err)}\n`));
		process.exit(1);
	});
}

View on GitHub (pinned to 9690622007)

Solutions

Install Docker (Docker Desktop on macOS, Docker Engine on Linux) so `docker` is on PATH
Verify with: which docker && docker info
Fix PATH in the environment where cleanup runs (CI/cron often has a minimal PATH)
If no docker resources exist to clean, skip the cleanup subcommand

Example fix

// before
$ runner cleanup
// Error: docker not found on PATH (required for cleanup).

// after (macOS)
$ brew install --cask docker && open -a Docker  # start daemon
$ runner cleanup

Defensive patterns

Strategy: validation

Validate before calling

import { which } from "@oh-my-pi/pi-utils";
if (process.argv[2] === "cleanup" && !which("docker")) {
  console.error("cleanup requires docker on PATH; install Docker first");
  process.exit(1);
}

Try / catch

try {
  await runCleanup();
} catch (err) {
  if (err instanceof Error && err.message.includes("docker not found on PATH")) {
    console.error("Install Docker (Desktop/Engine) and ensure `docker` is on PATH before cleanup");
    process.exitCode = 1;
    return;
  }
  throw err;
}

Prevention

Check `which docker` in CI/cron setup steps where PATH is often minimal
Install Docker on every host that may run benchmark cleanup
Use absolute docker path or fix PATH in non-interactive shells
Only invoke the cleanup subcommand on hosts that ran docker-based benchmarks

When it happens

Trigger: Calling the runner with 'cleanup' as the first CLI argument on a machine where which('docker') finds nothing.

Common situations: Running cleanup on a host without Docker Desktop/Engine installed; docker installed but not linked into PATH (e.g. manual install, PATH stripped in cron/CI); running the cleanup on a macOS host that only uses Apple container, not docker.

Related errors

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