jackwener/OpenCLI · error · CommandExecutionError

${label} request failed: ${err?.message ?? err}

Error message

${label} request failed: ${err?.message ?? err}

What it means

npmFetch wraps the underlying fetch call; when fetch itself rejects (DNS failure, connection refused/reset, TLS error, offline) it throws CommandExecutionError `${label} request failed: ${...}` with a hint to check registry.npmjs.org / api.npmjs.org reachability. This is only for network-level failures — HTTP error statuses are handled separately (e.g. 404 becomes EmptyResultError).

Source

Thrown at clis/npm/utils.js:51

export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
    const raw = value ?? defaultValue;
    const n = typeof raw === 'number' ? raw : Number(raw);
    if (!Number.isInteger(n) || n <= 0) {
        throw new ArgumentError(`npm ${label} must be a positive integer`);
    }
    if (n > maxValue) {
        throw new ArgumentError(`npm ${label} must be <= ${maxValue}`);
    }
    return n;
}

export async function npmFetch(url, label) {
    let resp;
    try {
        resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
    }
    catch (err) {
        throw new CommandExecutionError(
            `${label} request failed: ${err?.message ?? err}`,
            'Check that registry.npmjs.org / api.npmjs.org are reachable from this network.',
        );
    }
    if (resp.status === 404) {
        throw new EmptyResultError(label, `npm registry returned 404 for ${url}.`);
    }
    if (resp.status === 429) {
        throw new CommandExecutionError(
            `${label} returned HTTP 429 (rate limited)`,
            'npm throttles unauthenticated bursts; wait a few seconds and retry.',
        );
    }
    if (!resp.ok) {
        throw new CommandExecutionError(`${label} returned HTTP ${resp.status}`);
    }
    let body;
    try {

View on GitHub (pinned to 49907e53dc)

Solutions

1. Verify network access: `curl -sI https://registry.npmjs.org` from the same host.
2. Fix proxy setup — configure an undici ProxyAgent/dispatcher or run outside the proxy.
3. Trust the corporate CA via NODE_EXTRA_CA_CERTS if TLS interception causes failures.
4. Check NPM_REGISTRY / NPM_API environment overrides for typos (protocol, spelling, trailing slashes).
5. Catch CommandExecutionError and retry with backoff for transient failures; surface the included hint to the user.

Example fix

// before
await npmDownloads({ name: 'react', period: 'last-week' }); // offline -> CommandExecutionError
// after
try {
  return await npmDownloads({ name: 'react', period: 'last-week' });
} catch (e) {
  if (e.name === 'CommandExecutionError' && /request failed/.test(e.message)) {
    await new Promise((r) => setTimeout(r, 1000)); // retry transient network failure
    return await npmDownloads({ name: 'react', period: 'last-week' });
  }
  throw e;
}

// cheap pre-flight reachability check
const online = await fetch('https://registry.npmjs.org/-/ping', { method: 'HEAD' })
  .then(() => true)
  .catch(() => false);
if (!online) throw new Error('npm registry unreachable from this network');

function isNetworkFailure(err) {
  return err instanceof Error &&
    (err.name === 'CommandExecutionError' || /request failed|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|fetch failed/.test(String(err.message)));
}

async function withRetry(fn, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (e) {
      if (isNetworkFailure(e) && i < attempts - 1) {
        await new Promise((r) => setTimeout(r, 2 ** i * 500));
        continue;
      }
      throw e;
    }
  }
}
const pkg = await withRetry(() => npmPackage({ name: 'react' }));

When it happens

Trigger: Any registry request while offline, behind a blocking firewall/proxy, with broken DNS, a mistyped NPM_REGISTRY/NPM_API base URL, corporate TLS interception with an untrusted CA, or IPv6 issues — i.e. whenever `fetch()` throws instead of returning a response.

Common situations: CI with no network egress; corporate proxy requiring configuration (undici fetch ignores HTTP_PROXY env vars by default); DNS blocked for npmjs.org; VPN down; self-signed MITM proxy without NODE_EXTRA_CA_CERTS.

Related errors

• ${label} request failed: ${err?.message ?? err}
• FETCH_ERROR
• archive search request failed: ${error?.message || error}
• archive wayback request failed: ${error?.message || error}
• ${label} request failed: ${err?.message ?? err}

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