jackwener/OpenCLI · error · ArgumentError

${flagLabel} must be a positive integer

Error message

${flagLabel} must be a positive integer

What it means

requirePositiveInt validates numeric flag values (e.g. --timeout-seconds, --limit) ensuring they are integers >= 1. opencli throws this ArgumentError with the caller-supplied flag label and hint so the CLI surfaces which flag was wrong and how to use it.

Source

Thrown at clis/claude/utils.js:82

        throw new CommandExecutionError(message);
    }
    return state;
}

export function requireNonEmptyPrompt(prompt, commandName) {
    const text = String(prompt ?? '').trim();
    if (!text) {
        throw new ArgumentError(
            `${commandName} prompt cannot be empty`,
            `Example: opencli ${commandName} "hello"`,
        );
    }
    return text;
}

export function requirePositiveInt(value, flagLabel, hint) {
    if (!Number.isInteger(value) || value < 1) {
        throw new ArgumentError(`${flagLabel} must be a positive integer`, hint);
    }
    return value;
}

export function requireConversationId(value) {
    const id = String(value ?? '').trim();
    if (!id) {
        throw new ArgumentError(
            'claude detail requires a conversation id',
            'Example: opencli claude detail 123e4567-e89b-12d3-a456-426614174000',
        );
    }
    return id;
}

export async function getVisibleMessages(page) {
    const result = await page.evaluate(`(() => {
        var nodes = document.querySelectorAll('[data-testid="user-message"], ${MESSAGE_SELECTOR}');

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a whole number >= 1 for the flag, e.g. --timeout 30
2. Check that env vars/config feeding the flag are valid integers, not empty or '0'
3. Strip unit suffixes ('30s', '1500ms') before converting to a number

Example fix

// before
const limit = Number(process.env.LIMIT || 0); // 0 -> throws
requirePositiveInt(limit, '--limit', 'Example: opencli claude --limit 5');
// after
const limit = Number(process.env.LIMIT || 5);
requirePositiveInt(limit, '--limit', 'Example: opencli claude --limit 5');

function parsePositiveInt(v) {
  const n = Number(v);
  if (!Number.isInteger(n) || n < 1) {
    throw new Error(`Expected positive integer, got: ${v}`);
  }
  return n;
}
const timeout = parsePositiveInt(process.env.TIMEOUT);

function isPositiveInt(v) {
  return Number.isInteger(v) && v >= 1;
}

try {
  await command({ timeout });
} catch (e) {
  if (e instanceof ArgumentError && e.message.includes('must be a positive integer')) {
    console.error(`Invalid flag value: ${e.message}`);
    process.exitCode = 2;
  } else throw e;
}

When it happens

Trigger: Passing --timeout 0, a negative number, a float like 1.5, or a non-numeric value that was coerced to NaN to flags routed through requirePositiveInt (timeoutSeconds, limit).

Common situations: Default value 0 treated as 'no timeout' by the caller, unit confusion (milliseconds vs seconds producing 1500), parsing '30s' strings, JS Number('') === 0 from empty env vars.

Related errors

• 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 limit must be <= 100
• archive search query must not be empty

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