jackwener/OpenCLI · error · CommandExecutionError

${label} returned HTTP ${resp.status}

Error message

${label} returned HTTP ${resp.status}

What it means

mavenFetch() throws a CommandExecutionError when the response status is not ok and is not the specifically handled 404/429 cases — i.e. any other HTTP error (5xx, 403, 400, etc.) from search.maven.org.

Source

Thrown at clis/maven/utils.js:92

        resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
    }
    catch (err) {
        throw new CommandExecutionError(
            `${label} request failed: ${err?.message ?? err}`,
            'Check that search.maven.org is reachable from this network.',
        );
    }
    if (resp.status === 404) {
        throw new EmptyResultError(label, `Maven Central returned 404 for ${url}.`);
    }
    if (resp.status === 429) {
        throw new CommandExecutionError(
            `${label} returned HTTP 429 (rate limited)`,
            'Maven Central throttles bursts; wait a few seconds and retry.',
        );
    }
    if (!resp.ok) {
        throw new CommandExecutionError(`${label} returned HTTP ${resp.status}`);
    }
    let body;
    try {
        body = await resp.json();
    }
    catch (err) {
        throw new CommandExecutionError(`${label} returned malformed JSON: ${err?.message ?? err}`);
    }
    return body;
}

/** Convert epoch-ms (Maven Solr `timestamp`) to ISO-8601 UTC. Returns null for falsy/invalid. */
export function epochMsToIso(value) {
    if (value == null) return null;
    const n = typeof value === 'number' ? value : Number(value);
    if (!Number.isFinite(n) || n <= 0) return null;
    return new Date(n).toISOString().replace(/\.\d+Z$/, 'Z');
}

View on GitHub (pinned to 49907e53dc)

Solutions

1. Check the status code in the message to pick a response (5xx = server side, retry later; 403 = check IP/proxy).
2. URL-encode query parameters (encodeURIComponent) before building the URL.
3. Check Maven Central status (status.maven.org / central.sonatype.com) for outages.
4. Retry with backoff for transient 5xx; otherwise fix the request URL.

Example fix

// before
const url = `${MAVEN_BASE}?q=a:"${name}"`;
// after
const url = `${MAVEN_BASE}?q=${encodeURIComponent(`a:"${name}"`)}&rows=5`;

const url = `${MAVEN_BASE}?q=${encodeURIComponent(query)}&rows=${rows}`;
new URL(url); // throws early if the URL is malformed

null

try {
  return await mavenFetch(url, 'search');
} catch (err) {
  const m = /HTTP (\d{3})/.exec(err.message);
  if (m && Number(m[1]) >= 500) {
    await sleep(backoff(attempt));
    return mavenFetch(url, 'search');
  }
  throw err;
}

When it happens

Trigger: Maven Central returning 5xx during outages/maintenance, 403 from WAF/CDN blocking, 400 from a malformed query string that reached the server, or gateway 502/503/504 from infrastructure.

Common situations: Building a Solr query with characters that need encoding (spaces, ampersands) producing 400; search.maven.org having an outage; a CDN/WAF blocking the client IP; timeouts surfaced as 5xx from a proxy.

Related errors

• ${label} request failed: ${err?.message ?? err}
• ${label} returned malformed JSON: ${err?.message ?? err}
• API_ERROR
• API_ERROR
• arXiv API HTTP ${resp.status}

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