can1357/oh-my-pi · error · Error

--agents must be a positive integer

Error message

--agents must be a positive integer

What it means

runCleanse validates options.maxAgents before starting the cleanse runtime; when supplied it must be an integer greater than zero (default is 32 when omitted). A non-integer (e.g. 2.5, NaN) or zero/negative value aborts the cleanse run immediately with this Error.

Source

Thrown at packages/coding-agent/src/cleanse/index.ts:56

	/** Choose between discovered checkers; omit to run every checker without prompting. */
	pickTarget?(checkers: readonly CleanseCheckerDescriptor[]): Promise<CleanseTargetChoice>;
	/** Free-form request prompt when no runnable checker was discovered; `null` cancels. */
	promptRequest?(): Promise<string | null>;
}

/**
 * Detect project diagnostics, dispatch one bounded repair batch, and verify it.
 *
 * Cancellation flows exclusively through `signal`; the caller owns signal
 * sources (SIGINT for the CLI, Esc for the interactive overlay).
 */
export async function runCleanse(
	options: CleanseCommandOptions,
	ui: CleanseRunUi,
	signal: AbortSignal,
): Promise<CleanseCommandResult> {
	const maxAgents = options.maxAgents ?? 32;
	if (!Number.isInteger(maxAgents) || maxAgents <= 0) throw new Error("--agents must be a positive integer");
	const model = options.model?.trim() || DEFAULT_MODEL;
	const cwd = getProjectDir();
	let runtime: CleanseAgentRuntime | undefined;
	let runtimePromise: Promise<CleanseAgentRuntime> | undefined;
	let loopResult: CleanseLoopResult | undefined;
	const board = ui.board;
	const hooks: CleanseAgentHooks = {
		onStart: (name, assignment) => board.agentStarted(name, assignment),
		onProgress: (name, _assignment, progress) => board.agentProgress(name, progress),
		onFinish: (outcome, assignment) => board.agentFinished(outcome, assignment),
	};
	const checkerEvents: CleanseCheckerRunEvents = {
		onCheckerStart: checker => board.checkerStarted(checker),
		onCheckerEnd: (check, durationMs) => board.checkerFinished(check, durationMs),
	};
	const ensureRuntime = async (): Promise<CleanseAgentRuntime> => {
		runtimePromise ??= (async () => {
			board.phase(`Resolving model ${model}...`);

View on GitHub (pinned to 9690622007)

Solutions

1. Set maxAgents to a positive integer (or omit it to use the default 32).
2. If parsing from a string, validate with Number.isInteger(Number(raw)) and surface a clear CLI error before calling runCleanse.
3. Clamp at the call site: maxAgents = Math.max(1, Math.floor(userValue)).

Example fix

// before
await runCleanse({ maxAgents: Number(argv.agents), ... }, ui, signal); // NaN when --agents is empty
// after
const maxAgents = argv.agents ? Number(argv.agents) : undefined;
if (maxAgents !== undefined && (!Number.isInteger(maxAgents) || maxAgents <= 0)) {
  throw new CliUsageError("--agents must be a positive integer");
}
await runCleanse({ maxAgents, ... }, ui, signal);

const n = options.maxAgents;
if (n !== undefined && (!Number.isInteger(n) || n <= 0)) {
  throw new Error("--agents must be a positive integer");
}

function isValidMaxAgents(v: unknown): v is number {
  return typeof v === "number" && Number.isInteger(v) && v > 0;
}

try {
  await runCleanse(options, ui, signal);
} catch (err) {
  if (err instanceof Error && err.message.includes("--agents must be a positive integer")) {
    console.error("Invalid --agents value; use a positive integer (default 32).");
    process.exitCode = 2;
    return;
  }
  throw err;
}

When it happens

Trigger: Calling runCleanse with CleanseCommandOptions.maxAgents set to 0, a negative number, a non-integer float like 1.5, or NaN (e.g. from parsing a bad CLI string). Omitting maxAgents never triggers it.

Common situations: Passing --agents 0 or --agents abc through a wrapper that does Number(value) without checking NaN, or a config file where maxAgents was left at 0 or edited to a float.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• invalid {} argument: {}
• invalid Zero increment value: {}
• --trusted-extension requires a non-empty, non-flag value
• Invalid --state '${raw}'. Valid values: ${GALLERY_STATE_TOKE
• Invalid credential id: ${value}

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