What causes "${label} returned malformed JSON: ${err?.message ?? err}" in jackwener/OpenCLI?

Inspect the raw response (curl the same URL) to see what body is actually returned.

jackwener/OpenCLI · error · CommandExecutionError

${label} returned malformed JSON: ${err?.message ?? err}

Error message

${label} returned malformed JSON: ${err?.message ?? err}

What it means

mavenFetch() calls resp.json() to parse the response body; if parsing fails (invalid/truncated/non-JSON body), it throws a CommandExecutionError noting the label returned malformed JSON, including the underlying parse error.

Source

Thrown at clis/maven/utils.js:99

    }
    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

Inspect the raw response (curl the same URL) to see what body is actually returned.
Retry — this is often transient; add retry with backoff.
Check for proxy/captive-portal interference returning HTML instead of JSON.
Ensure your fetch environment handles gzip (proper user-agent/accept-encoding) and supports HTTPS to the real host.

Example fix

// before
const body = await mavenFetch(url, 'search');
// after
let body;
try {
  body = await mavenFetch(url, 'search');
} catch (err) {
  if (/malformed JSON/.test(String(err))) return withBackoff(() => mavenFetch(url, 'search'));
  throw err;
}

Defensive patterns

Strategy: retry

Validate before calling

const resp = await fetch(url);
const text = await resp.text();
try { JSON.parse(text); } catch { throw new Error('endpoint returned non-JSON'); }

Type guard

function isJsonObject(v) {
  return typeof v === 'object' && v !== null && !Array.isArray(v);
}

Try / catch

try {
  const body = await mavenFetch(url, 'search');
  if (!isJsonObject(body)) throw new Error('unexpected payload');
  return body;
} catch (err) {
  if (/malformed JSON/.test(err.message)) return withBackoff(() => mavenFetch(url, 'search'));
  throw err;
}

Prevention

Retry once or twice — truncated bodies are usually transient.
Detect captive portals/proxies injecting HTML by inspecting the raw body.
Verify gzip/encoding handling in your fetch runtime.
Pin to the real search.maven.org host; avoid intercepting middleboxes.

When it happens

Trigger: search.maven.org (or an intermediary proxy/captive portal) returning an HTML error page, empty body, truncated response, or otherwise invalid JSON with a 2xx status.

Common situations: Captive portal or corporate proxy injecting an HTML interstitial; CDN returning a compressed/garbled body the client cannot decode; intermittent infrastructure issue returning partial bodies; hitting a mirror/intercepting endpoint that returns HTML.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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