upstash/context7 · error · Context7Error

network_error

network_error

Error message

errorMessage(cause)

What it means

Context7Error with code "network_error" and retryable: true, thrown by fetchWithRetry when the fetch call itself fails (network-level failure, DNS, connection refused, TLS) and retries were exhausted or the error is non-retryable under the retry policy. The message is derived from the underlying cause via errorMessage(cause).

Source

Thrown at packages/sdk/src/http/index.ts:132

    init: RequestInit,
    method: "GET" | "POST",
    abortState: AbortState
  ): Promise<FetchResult> {
    const canRetry = method === "GET";

    for (let attempt = 0; attempt <= this.retry.retries; attempt++) {
      let response: Response;
      try {
        response = await this.fetch(url, init);
      } catch (cause) {
        if (abortState.signal?.aborted) {
          throw abortError(cause, abortState.timedOut());
        }
        if (canRetry && attempt < this.retry.retries) {
          await wait(this.retry.backoff(attempt), abortState.signal);
          continue;
        }
        throw new Context7Error(errorMessage(cause), {
          code: "network_error",
          retryable: true,
          cause,
        });
      }

      const metadata = extractResponseMetadata(response, attempt);
      this.onResponse?.(metadata);
      const shouldRetry =
        canRetry && this.retry.statuses.has(response.status) && attempt < this.retry.retries;
      if (!shouldRetry) return { response, metadata };

      await response.body?.cancel().catch(() => undefined);
      await wait(
        retryDelay(this.retry.backoff(attempt), metadata.rateLimit?.retryAfter),
        abortState.signal
      );
    }

View on GitHub (pinned to 80e681a507)

Solutions

1. Check the `cause` property of the error for the real underlying failure (ECONNREFUSED, ENOTFOUND, etc.) and fix that root cause.
2. Verify the baseUrl host/port is reachable (curl the endpoint) and DNS resolves.
3. Increase retries/backoff in config ({ retry: { retries: 10, backoff: ... } }) for flaky networks.
4. Since the error is marked retryable, wrap calls in your own retry-with-backoff loop for critical operations.
5. Check firewall/proxy/VPN settings and TLS certificates.

Example fix

// before
const data = await client.exec(cmd); // throws on transient network blips after 5 attempts
// after
try {
  const data = await client.exec(cmd);
} catch (e) {
  if (e instanceof Context7Error && e.code === 'network_error') {
    console.error('Network failure, cause:', e.cause); // inspect root cause
  }
  throw e;
}

// Pre-flight reachability check
const ok = await fetch(new URL('/health', baseUrl), { method: 'HEAD' }).then(r => r.ok).catch(() => false);
if (!ok) throw new Error(`Context7 endpoint ${baseUrl} unreachable`);

function isNetworkError(e: unknown): e is Context7Error {
  return e instanceof Context7Error && e.code === 'network_error' && e.retryable === true;
}

for (let i = 0; i < 3; i++) {
  try {
    return await client.exec(cmd);
  } catch (e) {
    if (!isNetworkError(e) || i === 2) throw e;
    await new Promise(r => setTimeout(r, 2 ** i * 250));
  }
}

When it happens

Trigger: fetch rejects (ECONNREFUSED, ENOTFOUND, ECONNRESET, certificate errors) and either the retry attempts (default 5) are exhausted, the status is not retryable per the retry policy, or a non-AbortError exception is thrown mid-request.

Common situations: Server down or wrong port/host in baseUrl, DNS failures, corporate proxy/firewall blocking, IPv6 issues, TLS cert problems, or flaky network in CI.

Related errors

• Failed to fetch ${item.path}: ${fileResponse.status}
• Port ${port} is in use, trying port ${port + 1}...
• errorBody.error || errorBody.message || res.statusText
• Failed to download ${skill.name}: ${downloadData.error}
• Please try again

AI-assisted analysis of upstash/context7@80e681a507 (2026-09-08). Data as JSON: /api/errors/4eb8e70f2ec5f3fb. Report an issue: GitHub.