jackwener/OpenCLI · error · CommandExecutionError

hf spaces request failed: ${err?.message ?? err}

Error message

hf spaces request failed: ${err?.message ?? err}

What it means

This error wraps any low-level failure of the fetch() call made by the `hf spaces` command to the Hugging Face Spaces listing API. The library throws a CommandExecutionError with the underlying network error's message so the CLI user sees why the HTTP request never completed. It is a network/transport-level failure, not an HTTP status error.

Source

Thrown at clis/hf/spaces.js:62

            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, {
                headers: { Accept: 'application/json', 'User-Agent': 'opencli/1.0 (+https://github.com/jackwener/opencli)' },
            });
        }
        catch (err) {
            throw new CommandExecutionError(`hf spaces request failed: ${err?.message ?? err}`);
        }
        if (resp.status === 429) {
            throw new CommandExecutionError(
                'hf spaces returned HTTP 429 (rate limited)',
                'Hugging Face throttles unauthenticated traffic; wait a few seconds and retry.',
            );
        }
        if (!resp.ok) {
            throw new CommandExecutionError(`hf spaces failed: HTTP ${resp.status}`);
        }
        let data;
        try {
            data = await resp.json();
        }
        catch (err) {
            throw new CommandExecutionError(`hf spaces returned malformed JSON: ${err?.message ?? err}`);
        }
        const list = Array.isArray(data) ? data : [];

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Check network connectivity (curl https://huggingface.co/api/spaces) and fix proxy/DNS/VPN issues
  2. If behind a proxy, set HTTPS_PROXY and ensure fetch honors it (undici EnvHttpProxyAgent or Node 24+)
  3. Upgrade to Node >= 18 so global fetch exists
  4. Retry after a transient outage; the underlying message in the error names the exact cause

Example fix

// before (Node 16, no global fetch)
const resp = await fetch(url);
// after
const { fetch: undiciFetch } = require('undici');
const resp = await undiciFetch(url, { headers: { Accept: 'application/json' } });
Defensive patterns

Strategy: try-catch

Validate before calling

// connectivity pre-check
const ok = await fetch('https://huggingface.co/api/spaces?limit=1', { method: 'HEAD' }).then(r => r.ok).catch(() => false);
if (!ok) console.warn('huggingface.co unreachable');

Try / catch

try {
  await hfSpaces(query);
} catch (e) {
  if (String(e.message).includes('request failed')) {
    // network-level: backoff and retry once, or degrade gracefully
    await new Promise(r => setTimeout(r, 2000));
    return null; // fallback path
  }
  throw e;
}

Prevention

When it happens

Trigger: The fetch() to https://huggingface.co/api/spaces throws: DNS resolution failure, connection refused/reset, TLS errors, request timeouts, or an offline machine. Any exception thrown by fetch itself (not an HTTP error status) is caught here.

Common situations: Running the CLI with no internet connection or behind a corporate proxy that blocks huggingface.co; DNS misconfiguration; firewall/VPN blocking outbound HTTPS; Node versions without global fetch (Node < 18) causing 'fetch is not defined'.

Related errors

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