jackwener/OpenCLI · error · CommandExecutionError

mdn search returned HTTP ${resp.status}

Error message

mdn search returned HTTP ${resp.status}

What it means

The MDN search API returned a non-OK, non-429 HTTP status (e.g. 500, 502, 503, 403). The adapter surfaces the raw status code in this CommandExecutionError. It signals a server-side or gateway problem rather than a client input issue.

Source

Thrown at clis/mdn/search.js:75

        const query = requireString(args.query, 'query');
        const limit = requireBoundedInt(args.limit, 10, 50);
        const locale = requireLocale(args.locale);
        const url = `${MDN_BASE}/api/v1/search?q=${encodeURIComponent(query)}&locale=${encodeURIComponent(locale)}&size=${limit}`;
        let resp;
        try {
            resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
        }
        catch (err) {
            throw new CommandExecutionError(`mdn search request failed: ${err?.message ?? err}`);
        }
        if (resp.status === 429) {
            throw new CommandExecutionError(
                'mdn search returned HTTP 429 (rate limited)',
                'MDN throttles bursty traffic; wait a few seconds and retry.',
            );
        }
        if (!resp.ok) {
            throw new CommandExecutionError(`mdn search returned HTTP ${resp.status}`);
        }
        let body;
        try {
            body = await resp.json();
        }
        catch (err) {
            throw new CommandExecutionError(`mdn search returned malformed JSON: ${err?.message ?? err}`);
        }
        const docs = Array.isArray(body?.documents) ? body.documents : [];
        if (!docs.length) {
            throw new EmptyResultError('mdn search', `No MDN results matched "${query}" (locale ${locale}).`);
        }
        return docs.slice(0, limit).map((doc, i) => ({
            rank: i + 1,
            title: String(doc.title ?? ''),
            slug: String(doc.slug ?? ''),
            locale: String(doc.locale ?? locale),
            summary: String(doc.summary ?? '').replace(/\s+/g, ' ').trim(),

View on GitHub (pinned to 49907e53dc)

Solutions

1. Check MDN status (visit developer.mozilla.org in a browser) and retry later if 5xx.
2. If 403, check whether your IP/proxy is blocked and adjust network setup.
3. Inspect the status code in the message to decide: 5xx retry with backoff, 4xx fix request.
4. Pin/fall back to a local docs search if MDN is unavailable.

Example fix

// before
const r = await mdnSearch({ query: 'weakmap' });
// after
try {
  const r = await mdnSearch({ query: 'weakmap' });
} catch (e) {
  const m = /HTTP (\d+)/.exec(e.message);
  if (m && +m[1] >= 500) return retryLater(e);
  throw e;
}

try { return await mdnSearch({ query }); } catch (e) {
  const m = /HTTP (\d+)/.exec(e.message);
  if (m && +m[1] >= 500) return retryWithBackoff(() => mdnSearch({ query }));
  throw e;
}

When it happens

Trigger: MDN server errors (5xx), API gateway/auth blocks (403), or any !resp.ok status other than the handled 429.

Common situations: MDN downtime or maintenance; CDN outages; blocked IPs; API changes returning unexpected statuses.

Related errors

• Ctrip flight API returned HTTP ${status || 'unknown'}
• ${label} returned HTTP ${resp.status}
• HTTP ${result.httpStatus} from /api/auth/session
• ${label} returned HTTP ${resp.status}
• Detached HEAD — checkout a branch first

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