jackwener/OpenCLI · error · ArgumentError

hf spaces limit must be <= 100

Error message

hf spaces limit must be <= 100

What it means

`hf spaces` caps `limit` at 100 because it fetches a single API page from huggingface.co/api/spaces. Requesting more than 100 throws this ArgumentError up front rather than silently clamping or paginating.

Source

Thrown at clis/hf/spaces.js:39

    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);

        let resp;
        try {
            resp = await fetch(url, {

View on GitHub (pinned to 49907e53dc)

Solutions

1. Use `--limit 100`, the maximum allowed per request.
2. Issue multiple calls (e.g. with different `--search` filters) if you need broader coverage.
3. Catch ArgumentError and clamp: `limit = Math.min(limit, 100)` in your wrapper.
4. Request pagination support upstream if you genuinely need >100 results.

Example fix

// before
hf spaces --limit 500
// after
hf spaces --limit 100

const n = Number(rawLimit ?? 20);
const limit = Math.min(Math.max(1, Number.isInteger(n) ? n : 20), 100);

function isWithinLimitCap(v) {
  return Number.isInteger(v) && v > 0 && v <= 100;
}

try {
  await run(['hf', 'spaces', '--limit', String(rawLimit)]);
} catch (err) {
  if (err instanceof ArgumentError && /limit must be <= 100/.test(err.message)) {
    console.warn('Limit capped at 100 (single API page); retrying with 100');
    await run(['hf', 'spaces', '--limit', '100']);
  } else throw err;
}

When it happens

Trigger: Running `hf spaces --limit 200`, `--limit 1000`, or computing a limit above 100 to 'get everything' in one call.

Common situations: Trying to export a large list of Spaces in one command; assuming the CLI paginates like other tools; porting scripts from APIs that allow larger page sizes.

Related errors

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

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