PaddlePaddle/PaddleOCR · error · NetworkError

Connection failed: ${message}

Error message

Connection failed: ${message}

What it means

NetworkError with 'Connection failed: <message>' is the catch-all for fetch rejections that are neither a user abort nor a timeout: DNS resolution failure, TCP connection refused, TLS errors, or fetch runtime incompatibilities. The original error's message is embedded and the original error is attached as `cause`. No HTTP response was ever received.

Source

Thrown at api_sdk/typescript/src/internal/http.ts:221

      abort();
    } else {
      signal?.addEventListener("abort", abort, { once: true });
    }
    try {
      resp = await this.fetchImpl(url, {
        ...init,
        headers,
        signal: abortController.signal,
      });
    } catch (e: unknown) {
      if (signal?.aborted) {
        throw userAbortReason(signal);
      }
      if (timeoutController.signal.aborted) {
        throw new RequestTimeoutError(effectiveTimeout, { cause: e });
      }
      const message = e instanceof Error ? e.message : String(e);
      throw new NetworkError(`Connection failed: ${message}`);
    } finally {
      clearTimeout(timeoutID);
      signal?.removeEventListener("abort", abort);
    }

    if (resp.ok) return resp;

    let text = await resp.text();
    try {
      const payload = JSON.parse(text) as { msg?: string; message?: string; errorMsg?: string };
      text = payload.msg || payload.message || payload.errorMsg || text;
    } catch {
      // Keep raw response text.
    }
    if (resp.status === 401 || resp.status === 403) {
      throw new AuthError(`Authentication failed: ${text}`);
    } else if (resp.status === 400) {
      throw new InvalidRequestError(`Bad request: ${text}`);

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Verify connectivity to the API host directly: curl -v https://<api-host>/ — if that fails, fix DNS/firewall/proxy first
2. Read e.cause for the real reason (ENOTFOUND, ECONNREFUSED, certificate errors) and address that specific failure
3. For corporate proxies, set HTTPS_PROXY/HTTP_PROXY or inject a proxy-aware Agent via the SDK's custom fetchImpl
4. Ensure Node.js >= 18 (built-in fetch) or supply a compatible fetchImpl

Example fix

try {
  const jobs = await client.getBatchStatus(batchId);
} catch (e) {
  if (e instanceof NetworkError) {
    console.error("underlying cause:", e.cause); // e.g. ENOTFOUND
    throw new Error("API unreachable — check network/proxy config");
  }
}

async function canReach(host: string): Promise<boolean> {
  try {
    await fetch(`https://${host}`, { method: "HEAD" });
    return true;
  } catch {
    return false;
  }
}

function isNetworkError(e: unknown): e is NetworkError {
  return e instanceof NetworkError;
}

try {
  const s = await poller.getStatus(jobId);
} catch (e) {
  if (e instanceof NetworkError) {
    // inspect e.cause: ENOTFOUND -> DNS, ECONNREFUSED -> firewall, CERT_* -> proxy TLS
    failFastWithDiagnostics(e.cause);
  }
  throw e;
}

When it happens

Trigger: Any request when the API host cannot be reached: wrong/custom base URL with an unresolvable hostname, firewall or egress rules blocking the endpoint, self-signed certificate behind a corporate proxy, offline environment, or passing a fetchImpl that lacks required runtimes (e.g. undici vs Node version mismatch).

Common situations: CI containers without outbound internet; corporate TLS-inspecting proxies requiring custom CA bundles; air-gapped environments; typos in the configured endpoint; Node < 18 where global fetch is unavailable; IPv6-only networks misbehaving.

Related errors

• Request timed out after ${timeoutMs}ms
• Either fileUrl or filePath is required.
• OCR result item is missing result.ocrResults.
• OCR result page is missing prunedResult.
• Document parsing result item is missing result.layoutParsing

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/c9d43e7e19770818. Report an issue: GitHub.