jackwener/OpenCLI · error · ArgumentError

hf spaces limit must be a positive integer

Error message

hf spaces limit must be a positive integer

What it means

`hf spaces` validates that the `limit` argument, after `Number()` coercion, is an integer greater than 0. Values like 0, negative numbers, NaN (from non-numeric strings), or fractional numbers throw this ArgumentError before any request is made.

Source

Thrown at clis/hf/spaces.js:36

    domain: 'huggingface.co',
    strategy: Strategy.PUBLIC,
    browser: false,
    args: [
        { name: 'sort', type: 'string', default: 'likes', help: `Sort key: ${SORT_OPTIONS.join(', ')}` },
        { name: 'search', type: 'string', required: false, help: 'Optional name/owner substring filter (e.g. "stability", "openai/")' },
        { name: 'sdk', type: 'string', required: false, help: 'Filter by Space SDK: gradio / streamlit / docker / static' },
        { name: 'limit', type: 'int', default: 20, help: 'Max spaces (max 100; one API page).' },
    ],
    columns: ['rank', 'id', 'author', 'sdk', 'likes', 'tags', 'lastModified', 'url'],
    func: async (args) => {
        const sortRaw = String(args.sort ?? 'likes').toLowerCase();
        const sort = SORT_ALIAS[sortRaw] ?? sortRaw;
        if (!SORT_OPTIONS.includes(sort)) {
            throw new ArgumentError(`hf spaces sort must be one of ${SORT_OPTIONS.join(', ')}`);
        }
        const limit = Number(args.limit ?? 20);
        if (!Number.isInteger(limit) || limit <= 0) {
            throw new ArgumentError('hf spaces limit must be a positive integer');
        }
        if (limit > 100) {
            throw new ArgumentError('hf spaces limit must be <= 100');
        }
        const sdk = args.sdk == null ? '' : String(args.sdk).trim().toLowerCase();
        const allowedSdks = new Set(['', 'gradio', 'streamlit', 'docker', 'static']);
        if (!allowedSdks.has(sdk)) {
            throw new ArgumentError(`hf spaces sdk must be one of gradio / streamlit / docker / static`);
        }

        const url = new URL('https://huggingface.co/api/spaces');
        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 (sdk) url.searchParams.set('sdk', sdk);

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a positive integer, e.g. `hf spaces --limit 50`.
2. Check the value in your wrapper script before invoking: it must satisfy Number.isInteger(n) && n > 0.
3. Remember the hard cap is 100 (one API page) — use values 1–100.
4. Catch ArgumentError and fall back to the default limit of 20 when input is invalid.

Example fix

// before
const limit = process.env.LIMIT || 0; // 0 -> error
hf spaces --limit ${limit}
// after
const limit = Math.max(1, parseInt(process.env.LIMIT, 10) || 20);
hf spaces --limit ${limit}

const n = Number(rawLimit ?? 20);
if (!Number.isInteger(n) || n <= 0) throw new Error('limit must be a positive integer');

function isValidLimit(v) {
  return Number.isInteger(v) && v > 0;
}

try {
  await run(['hf', 'spaces', '--limit', String(rawLimit)]);
} catch (err) {
  if (err instanceof ArgumentError && /limit must be a positive integer/.test(err.message)) {
    console.warn('Invalid limit; using default 20');
    await run(['hf', 'spaces']);
  } else throw err;
}

When it happens

Trigger: Running `hf spaces --limit 0`, `--limit -5`, `--limit abc` (NaN), or `--limit 10.5` (non-integer after Number coercion).

Common situations: Scripting the CLI with a variable that is empty or unset (coerces to 0 or NaN); typo like `--limit 2O` (letter O); passing a float from a computed value; copying `limit=0` defaults from other tools.

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 spaces sort must be one of ${SORT_OPTIONS.join(', ')}
• hf spaces sdk must be one of gradio / streamlit / docker / s
• INVALID_ARGUMENT
• INVALID_ARGUMENT
• INVALID_ARGUMENT

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