jackwener/OpenCLI · error · ArgumentError

hf models limit must be a positive integer

Error message

hf models limit must be a positive integer

What it means

ArgumentError thrown at clis/hf/models.js:35 when the --limit argument, coerced with Number(), is not an integer or is <= 0. The library validates the limit before constructing the /api/models query because the HF API requires a positive integer limit parameter.

Source

Thrown at clis/hf/models.js:35

    domain: 'huggingface.co',
    strategy: Strategy.PUBLIC,
    browser: false,
    args: [
        { name: 'sort', type: 'string', default: 'downloads', help: `Sort key: ${SORT_OPTIONS.join(', ')}` },
        { name: 'search', type: 'string', required: false, help: 'Optional name/owner substring filter (e.g. "llama", "mistralai/")' },
        { name: 'pipeline', type: 'string', required: false, help: 'Filter by pipeline tag (e.g. text-generation, image-classification)' },
        { name: 'limit', type: 'int', default: 20, help: 'Max models (max 100; one API page).' },
    ],
    columns: ['rank', 'id', 'author', 'pipelineTag', 'downloads', 'likes', 'tags', 'lastModified', 'url'],
    func: async (args) => {
        const sortRaw = String(args.sort ?? 'downloads').toLowerCase();
        const sort = SORT_ALIAS[sortRaw] ?? sortRaw;
        if (!SORT_OPTIONS.includes(sort)) {
            throw new ArgumentError(`hf models sort must be one of ${SORT_OPTIONS.join(', ')}`);
        }
        const limit = Number(args.limit ?? 20);
        if (!Number.isInteger(limit) || limit <= 0) {
            throw new ArgumentError('hf models limit must be a positive integer');
        }
        if (limit > 100) {
            throw new ArgumentError('hf models limit must be <= 100');
        }

        const url = new URL('https://huggingface.co/api/models');
        url.searchParams.set('sort', sort);
        url.searchParams.set('direction', '-1');
        url.searchParams.set('limit', String(limit));
        url.searchParams.set('full', 'true');
        if (args.search) url.searchParams.set('search', String(args.search));
        if (args.pipeline) url.searchParams.set('pipeline_tag', String(args.pipeline));

        let resp;
        try {
            resp = await fetch(url, {
                headers: {
                    'Accept': 'application/json',

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a whole number >= 1, e.g. --limit 20.
2. Omit the flag to use the default of 20.
3. Strip formatting from scripted values (no commas, no units) and ensure the variable is set before interpolation.
4. Validate with Number.isInteger(n) && n > 0 in any wrapper script before invoking.

Example fix

// before
opencli hf models --limit "$ROWS"   # ROWS is empty -> NaN
// after
ROWS=${ROWS:-20}; opencli hf models --limit "$ROWS"

function validateLimit(raw) {
  const n = Number(raw ?? 20);
  if (!Number.isInteger(n) || n <= 0) throw new Error(`limit must be a positive integer, got ${JSON.stringify(raw)}`);
  return n;
}

try {
  await run(`hf models --limit ${limit}`);
} catch (e) {
  if (String(e.message).includes('limit must be a positive integer')) {
    console.error(`--limit "${limit}" is not a positive integer; using default 20`);
    await run('hf models');
  } else throw e;
}

When it happens

Trigger: Passing `hf models --limit` with a non-integer (e.g. 12.5), zero, a negative number, or a value that Number() turns into NaN (e.g. --limit abc, --limit '', --limit '20x').

Common situations: Shell variable interpolating empty (--limit "$LIMIT" with LIMIT unset); typo like --limit 2O (letter O) silently producing NaN; scripts computing limit from arithmetic that yields 0 or a float; copy-pasted limits like '1,000' with a thousands separator.

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

• hf models sort must be one of ${SORT_OPTIONS.join(', ')}
• hf models limit must be <= 100
• hf paper id cannot be empty
• hf paper id "${args.id}" is not a valid arXiv id
• hf spaces sort must be one of ${SORT_OPTIONS.join(', ')}

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