can1357/oh-my-pi · error · CliUsageError

Expected integer for --${name}, got "${raw}"

Error message

Expected integer for --${name}, got "${raw}"

What it means

parse() validates flags declared with kind "integer": it parses the raw string with Number.parseInt and throws CliUsageError if the result is NaN. Only base-10 integer strings are accepted; anything else (letters, empty, float-with-unit) is rejected.

Source

Thrown at packages/utils/src/cli.ts:233

					allowPositionals: true,
					strict,
				});
			} catch (error) {
				throw new CliUsageError(error instanceof Error ? error.message : String(error));
			}
		})();

		// Convert raw values to proper types and validate
		const flags: Record<string, unknown> = {};
		for (const [name, desc] of Object.entries(flagDefs)) {
			const raw = rawValues[name];
			if (desc.kind === "integer") {
				if (raw === undefined || typeof raw === "boolean") {
					flags[name] = desc.default ?? undefined;
				} else {
					const n = Number.parseInt(raw as string, 10);
					if (Number.isNaN(n)) {
						throw new CliUsageError(`Expected integer for --${name}, got "${raw}"`);
					}
					flags[name] = n;
				}
			} else if (desc.kind === "boolean") {
				flags[name] =
					raw !== undefined ? Boolean(raw) : desc.default !== undefined ? Boolean(desc.default) : undefined;
			} else {
				// string
				const val = raw !== undefined && typeof raw !== "boolean" ? raw : (desc.default ?? undefined);
				// Validate options constraint
				if (val !== undefined && desc.options && !Array.isArray(val)) {
					if (!desc.options.includes(val as string)) {
						throw new CliUsageError(
							`Expected --${name} to be one of: ${[...desc.options].join(", ")}; got "${val}"`,
						);
					}
				}
				flags[name] = val;

View on GitHub (pinned to 9690622007)

Solutions

1. Pass a plain base-10 integer, e.g. --retries 3.
2. Remove any unit suffix or whitespace from the value.
3. Quote values starting with '-' so the shell doesn't treat them as flags: --offset "-5".
4. Check the default in the flag definition if you intended to omit the flag entirely.

Example fix

// before
cli.parse(['--retries', 'three']); // CliUsageError
// after
cli.parse(['--retries', '3']);

const raw = String(flagValue);
if (!/^-?\d+$/.test(raw.trim())) {
  throw new Error(`--retries must be an integer, got "${raw}"`);
}

try {
  const { retries } = cli.parse(argv);
} catch (err) {
  if (err instanceof CliUsageError && err.message.startsWith('Expected integer')) {
    console.error(err.message);
    process.exitCode = 2;
    return;
  }
  throw err;
}

When it happens

Trigger: Passing a non-integer value to an integer-typed flag, e.g. `--retries abc`, `--retries 1.5.0`, `--limit ''`, or `--concurrency 3s`.

Common situations: Typos in numeric flags, pasting values with units from docs ("10m"), or shell variables expanding to empty strings.

Related errors

• invalid {} argument: {}
• invalid Zero increment value: {}
• --agents must be a positive integer
• --trusted-extension requires a non-empty, non-flag value
• Invalid --state '${raw}'. Valid values: ${GALLERY_STATE_TOKE

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