jackwener/OpenCLI · error · ArgumentError

--${label} must be an integer between 1 and ${maximum}

Error message

--${label} must be an integer between 1 and ${maximum}

What it means

This ArgumentError is thrown by the positiveInteger validator in clis/xiaoyuzhou/history.js when a user-supplied numeric CLI option (--limit or --max-pages) is not an integer between 1 and its allowed maximum (5000 for limit, 1000 for max-pages). The CLI validates these before making any network requests, so it is purely an input problem, not an API problem.

Source

Thrown at clis/xiaoyuzhou/history.js:20

import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
import { loadXiaoyuzhouCredentials, requestXiaoyuzhouJson } from './auth.js';

const DEFAULT_LIMIT = 20;
const MAX_LIMIT = 5000;
const DEFAULT_MAX_PAGES = 500;
const HARD_MAX_PAGES = 1000;
const HISTORY_ENDPOINT = '/v1/episode-played/list-history';
const PROGRESS_ENDPOINT = '/v1/playback-progress/list';
const XIAOYUZHOU_ID = /^[0-9a-f]{24}$/i;

function isRecord(value) {
    return value !== null && typeof value === 'object' && !Array.isArray(value);
}

function positiveInteger(value, label, maximum) {
    const parsed = Number(value);
    if (!Number.isInteger(parsed) || parsed < 1 || parsed > maximum) {
        throw new ArgumentError(`--${label} must be an integer between 1 and ${maximum}`);
    }
    return parsed;
}

function requiredId(value, label) {
    if (typeof value !== 'string' || !XIAOYUZHOU_ID.test(value)) {
        throw new CommandExecutionError(`Xiaoyuzhou history returned an invalid ${label}`);
    }
    return value.toLowerCase();
}

function requiredString(value, label) {
    if (typeof value !== 'string' || !value.trim()) {
        throw new CommandExecutionError(`Xiaoyuzhou history returned an invalid ${label}`);
    }
    return value.trim();
}

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Pass an integer between 1 and 5000 for --limit, or use --all (which ignores --limit) to fetch the full history.
  2. Use --max-pages between 1 and 1000; the default 500 is usually sufficient.
  3. Fix the shell variable feeding the option (quote/default it, e.g. LIMIT=${LIMIT:-20}) so it is non-empty and numeric.
  4. If you need more rows than the caps allow, paginate by re-running with a cursor or request a higher limit in the library config rather than forcing the CLI cap.

Example fix

// before
$ xiaoyuzhou history --limit 10000
ArgumentError: --limit must be an integer between 1 and 5000
// after
$ xiaoyuzhou history --limit 5000 --max-pages 1000
# or to fetch everything:
$ xiaoyuzhou history --all
Defensive patterns

Strategy: validation

Validate before calling

function isValidPositiveInt(v, max) { const n = Number(v); return Number.isInteger(n) && n >= 1 && n <= max; }
if (!isValidPositiveInt(process.argv.limit, 5000)) throw new Error('--limit must be 1..5000');
if (!isValidPositiveInt(process.argv.maxPages, 1000)) throw new Error('--max-pages must be 1..1000');

Type guard

function isPositiveInteger(v, max) { return Number.isInteger(Number(v)) && Number(v) >= 1 && Number(v) <= max; }

Try / catch

try { await cli.run(['xiaoyuzhou', 'history', '--limit', String(limit)]); } catch (e) { if (e.name === 'ArgumentError') { console.error(`Bad option: ${e.message}`); process.exitCode = 2; } else throw e; }

Prevention

When it happens

Trigger: Running `xiaoyuzhou history --limit 0`, `--limit abc`, `--limit 5001`, `--max-pages 0`, `--max-pages 1001`, or passing a fractional value like `--limit 2.5`. Values are coerced with Number(), so numeric strings are accepted but non-numeric strings, NaN, fractions, zero, negatives, and values above the max all throw.

Common situations: Scripting the CLI with an empty or misparsed shell variable (e.g. --limit "" becomes NaN); copying a max from docs of a different tool; trying to fetch more than 5000 rows with --limit instead of using --all; passing --max-pages too low and expecting it to be clamped rather than rejected.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

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