jackwener/OpenCLI · error · CommandExecutionError

archive snapshots request failed: ${error?.message || error}

Error message

archive snapshots request failed: ${error?.message || error}

What it means

CommandExecutionError wrapping any exception (network error, DNS failure, timeout, fetch rejection) raised while requesting the Wayback CDX API at http://web.archive.org/cdx/search/cdx. The original error message is preserved in the new message via `error?.message || error`. Note the library deliberately uses HTTP because the HTTPS CDX endpoint returns 503.

Source

Thrown at clis/archive/snapshots.js:76

        // Wayback CDX is served on HTTP only; the HTTPS endpoint returns 503.
        const apiUrl = new URL('http://web.archive.org/cdx/search/cdx');
        apiUrl.searchParams.set('url', target);
        apiUrl.searchParams.set('output', 'json');
        apiUrl.searchParams.set('limit', String(limit));
        if (args.from) apiUrl.searchParams.set('from', String(args.from));
        if (args.to) apiUrl.searchParams.set('to', String(args.to));

        let resp;
        try {
            resp = await fetch(apiUrl, {
                headers: {
                    'Accept': 'application/json',
                    'User-Agent': 'opencli/1.0 (+https://github.com/jackwener/opencli)',
                },
            });
        } catch (error) {
            throw new CommandExecutionError(`archive snapshots request failed: ${error?.message || error}`);
        }
        if (!resp.ok) {
            throw new CommandExecutionError(`archive snapshots failed: HTTP ${resp.status}`);
        }
        let data;
        try {
            data = await resp.json();
        } catch (error) {
            throw new CommandExecutionError(`archive snapshots returned malformed JSON: ${error?.message || error}`);
        }

        // CDX returns an array of arrays; the first row is the header.
        if (!Array.isArray(data)) {
            throw new CommandExecutionError('archive snapshots returned malformed CDX payload: top-level payload must be an array');
        }
        if (data.length < 2) {
            throw new EmptyResultError('archive snapshots', `No Wayback snapshots for "${target}".`);
        }

View on GitHub (pinned to 49907e53dc)

Solutions

Check network connectivity and confirm web.archive.org is reachable: curl -I http://web.archive.org/cdx/search/cdx?url=example.org&output=json
If behind a proxy, configure HTTP_PROXY/HTTPS_PROXY correctly for the runtime.
Retry after a short delay — Wayback CDX is often intermittently overloaded; backoff on repeated failures.
Ensure your environment does not force an HTTPS upgrade that breaks the HTTP-only CDX endpoint.

Example fix

// retry wrapper around the CLI call
for (let i = 0; i < 3; i++) {
  try { return await runSnapshots(url); }
  catch (e) {
    if (!String(e.message).includes('request failed')) throw e;
    await new Promise(r => setTimeout(r, 2 ** i * 1000));
  }
}

Defensive patterns

Strategy: retry

Validate before calling

// Reachability pre-check before running the command
const ok = await fetch('http://web.archive.org/cdx/search/cdx?url=example.org&output=json&limit=1')
  .then(r => r.ok).catch(() => false);
if (!ok) console.warn('web.archive.org unreachable; check network/proxy');

Try / catch

async function withRetry(fn, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    try { return await fn(); }
    catch (e) {
      if (!/snapshots request failed/.test(e.message) || i === attempts - 1) throw e;
      await new Promise(r => setTimeout(r, 2 ** i * 1000));
    }
  }
}

Prevention

Set HTTP_PROXY/HTTPS_PROXY when behind corporate proxies.
Add exponential backoff for archive.org calls in automation.
Monitor web.archive.org status before large batch jobs.
Remember the CDX API is HTTP-only; do not force HTTPS upgrades.

When it happens

Trigger: fetch() rejects during `opencli archive snapshots <url>`: DNS resolution failure, connection refused/reset, TLS interception problems, request timeout, or offline network.

Common situations: Being offline or behind a corporate proxy/firewall blocking web.archive.org; DNS misconfiguration; corporate MITM proxies breaking plain-HTTP requests; Wayback temporarily unreachable or rate-limiting.

Related errors

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