jackwener/OpenCLI · error · ArgumentError

${label} must be a positive integer

Error message

${label} must be a positive integer

What it means

parseLimit throws this ArgumentError when the limit value is not a positive integer (non-numeric string, 0, negative, float, NaN). The CLI validates pagination input locally before hitting the API to avoid pointless requests.

Source

Thrown at clis/_atlassian/shared.js:278

export function requirePayloadString(value, field, label) {
    if (typeof value !== 'string' && typeof value !== 'number') {
        throw new CommandExecutionError(`${label} did not include a stable ${field}.`);
    }
    const s = String(value).trim();
    if (!s) throw new CommandExecutionError(`${label} did not include a stable ${field}.`);
    return s;
}

export function requireNonEmptyRows(rows, label, hint) {
    if (!rows.length) throw new EmptyResultError(label, hint);
    return rows;
}

export function parseLimit(value, defaultValue = 20, maxValue = 100, label = 'limit') {
    const raw = value ?? defaultValue;
    const n = typeof raw === 'number' ? raw : Number(raw);
    if (!Number.isInteger(n) || n <= 0) {
        throw new ArgumentError(`${label} must be a positive integer`);
    }
    if (n > maxValue) {
        throw new ArgumentError(`${label} must be <= ${maxValue}`);
    }
    return n;
}

export function requireExecute(args, commandName) {
    if (args.execute !== true) {
        throw new ArgumentError(`${commandName} requires --execute to perform a remote write`);
    }
}

export async function readUtf8File(filePath) {
    const path = requireString(filePath, '--file');
    let fileStat;
    try {
        fileStat = await stat(path);

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a positive whole number, e.g. --limit 25.
2. Sanitize/validate shell variables before use: case "${N}" in ''|*[!0-9]*) exit 1;; esac or use ${N:?}.
3. Check for invisible characters/units in the value (tr -d '[:space:]').
4. In scripts, compute counts with integer arithmetic only.

Example fix

// before
const limit = process.env.PAGE_SIZE; // "50 items"
await run(['--limit', limit]);
// after
const limit = parseInt(process.env.PAGE_SIZE, 10);
if (!Number.isInteger(limit) || limit <= 0) throw new Error('PAGE_SIZE must be a positive integer');
await run(['--limit', String(limit)]);

function parseLimitSafe(v, def = 20) {
  if (v == null || v === '') return def;
  const n = Number(v);
  if (!Number.isInteger(n) || n <= 0) throw new Error(`limit must be a positive integer, got: ${v}`);
  return n;
}

function isPositiveInt(v) { return typeof v === 'number' && Number.isInteger(v) && v > 0; }

try {
  await listCmd({ limit: rawLimit });
} catch (e) {
  if (e instanceof ArgumentError || /must be a positive integer/.test(e.message)) {
    console.error(`Bad --limit value "${rawLimit}" — use a whole number > 0.`);
    process.exitCode = 2;
  } else throw e;
}

When it happens

Trigger: Passing --limit abc, --limit 0, --limit -5, --limit 2.5, or an empty-string limit that coerces to NaN.

Common situations: Shell variables containing '20 items' or empty strings; copying a float from config; off-by-one scripts computing 0 results; typos like --limit=1O (letter O).

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} must be <= ${maxValue}
• zhihu collection --${name} must be a non-negative integer
• ${label} is required
• dblp ${label} must be a positive integer
• dblp ${label} must be <= ${maxValue}

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