jackwener/OpenCLI · error · ArgumentError

${label} must be a positive integer

Error message

${label} must be a positive integer

What it means

`parsePositiveIntegerOption` validates that an option value is a string of digits that parses to a safe integer >= 1. The first throw fires when the raw value fails the `/^\d+$/` test — it contains non-digit characters (signs, spaces, decimals, letters) or is empty.

Source

Thrown at clis/codex/sidebar.js:32

    const label = normalizeMatch(project.project);
    const projectPath = normalizeMatch(project.projectPath);
    const needle = normalizeMatch(query);
    if (!needle)
        return true;
    return label === needle
        || label.includes(needle)
        || projectPath === needle
        || projectPath.endsWith(`/${needle}`);
}

export function hasConversationTarget(kwargs) {
    return !!(kwargs?.project || kwargs?.conversation || kwargs?.index || kwargs?.['thread-id']);
}

export function parsePositiveIntegerOption(raw, label) {
    const value = cleanText(raw);
    if (!/^\d+$/.test(value)) {
        throw new ArgumentError(`${label} must be a positive integer`);
    }
    const parsed = Number.parseInt(value, 10);
    if (!Number.isSafeInteger(parsed) || parsed < 1) {
        throw new ArgumentError(`${label} must be a positive integer`);
    }
    return parsed;
}

export function parseOptionalPositiveIntegerOption(raw, label) {
    if (raw == null || cleanText(raw) === '') {
        return null;
    }
    return parsePositiveIntegerOption(raw, label);
}

export function requireNonEmptyOption(raw, label) {
    const value = cleanText(raw);
    if (!value) {

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a plain positive integer string, e.g. `--index 2` (1-based).
2. Trim whitespace and strip any non-digit characters from the value before calling.
3. Validate user input in your wrapper before forwarding options.
4. Use `parseOptionalPositiveIntegerOption` when the value may legitimately be absent.

Example fix

// before
parsePositiveIntegerOption('1.5', 'index'); // throws
// after
parsePositiveIntegerOption('2', 'index'); // OK

function isValidPositiveInt(v) {
  return typeof v === 'string' && /^\d+$/.test(v) && Number.isSafeInteger(Number(v)) && Number(v) >= 1;
}
if (!isValidPositiveInt(rawIndex)) throw new Error(`index must be a positive integer, got ${JSON.stringify(rawIndex)}`);

const isPositiveIntOption = (v) => typeof v === 'string' && /^\d+$/.test(v) && Number(v) >= 1 && Number.isSafeInteger(Number(v));

try {
  await sidebarCmd({ index: raw });
} catch (e) {
  if (String(e.message).endsWith('must be a positive integer')) {
    console.error(`Bad option value: ${JSON.stringify(raw)}; pass a 1-based integer like 2`);
  } else throw e;
}

When it happens

Trigger: Passing e.g. `--index 0x2`, `--index 1.5`, `--index -3`, `--index ' 4'`, `--index abc`, or an empty string to an option routed through `parsePositiveIntegerOption` (index, conversation, thread-id numeric paths).

Common situations: Users supply 0-based indices, decimal indices, or copy values with surrounding whitespace/currency of other formats; shell quoting yields empty strings.

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

• ${label} cannot be empty
• archive search sort must be one of ${SORT_OPTIONS.join(', ')
• archive search mediatype must be one of ${MEDIATYPES.join(',
• archive search limit must be a positive integer
• archive search query must not be empty

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/348820762b6d4bf7. Report an issue: GitHub.