What causes "hf spaces sort must be one of ${SORT_OPTIONS.join(', ')}" in jackwener/OpenCLI?

Use one of: likes, created_at, last_modified (e.g. `hf spaces --sort last_modified`).

jackwener/OpenCLI · error · ArgumentError

hf spaces sort must be one of ${SORT_OPTIONS.join(', ')}

Error message

hf spaces sort must be one of ${SORT_OPTIONS.join(', ')}

What it means

`hf spaces` only accepts three sort keys — 'likes', 'created_at', 'last_modified' (with aliases 'lastmodified'/'createdat') — because the Spaces API rejects other sort values such as 'trending'. If the resolved sort value after alias normalization is not in SORT_OPTIONS, an ArgumentError is thrown before any network request is made.

Source

Thrown at clis/hf/spaces.js:32

    site: 'hf',
    name: 'spaces',
    access: 'read',
    description: 'Top Hugging Face Spaces (likes / created_at / last_modified).',
    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));

View on GitHub (pinned to 49907e53dc)

Solutions

Use one of: likes, created_at, last_modified (e.g. `hf spaces --sort last_modified`).
Use the aliases `lastmodified` or `createdat` if you prefer camel-free input.
Run `hf spaces --help` to see the supported sort keys.
Catch ArgumentError and map/normalize your sort value before invoking the command.

Example fix

// before
hf spaces --sort trending
// after
hf spaces --sort likes   // trending is not supported by the Spaces API

Defensive patterns

Strategy: validation

Validate before calling

const SORT_OPTIONS = ['likes', 'created_at', 'last_modified'];
const SORT_ALIAS = { lastmodified: 'last_modified', createdat: 'created_at' };
const sort = SORT_ALIAS[String(raw).toLowerCase()] ?? String(raw).toLowerCase();
if (!SORT_OPTIONS.includes(sort)) throw new Error(`sort must be one of ${SORT_OPTIONS.join(', ')}`);

Type guard

function isValidSort(v) {
  return ['likes', 'created_at', 'last_modified'].includes(String(v ?? 'likes').toLowerCase());
}

Try / catch

try {
  await run(['hf', 'spaces', '--sort', sort]);
} catch (err) {
  if (err instanceof ArgumentError && /sort must be one of/.test(err.message)) {
    console.warn(`Invalid sort "${sort}"; defaulting to likes`);
    await run(['hf', 'spaces', '--sort', 'likes']);
  } else throw err;
}

Prevention

Only use likes / created_at / last_modified for hf spaces — 'trending' is rejected by the Spaces API itself
Do not copy sort keys from hf models / hf datasets; the allowed sets differ
Run hf spaces --help to confirm the accepted sort keys
Normalize case and hyphens/underscores (lastmodified -> last_modified) before passing sort

When it happens

Trigger: Running `hf spaces --sort trending` or any sort value outside likes/created_at/last_modified (e.g. 'downloads', 'modified', 'Likes' is fine due to lowercasing, but 'trending' is not).

Common situations: Copying sort values from `hf models` or `hf datasets` (which accept more keys like 'downloads' or 'trending') into `hf spaces`; assuming GitHub-style sort names; guessing sort keys without reading --help.

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

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