PaddlePaddle/PaddleOCR · error · NetworkError

Connection failed: {e}

Error message

Connection failed: {e}

What it means

NetworkError raised when requests.get for a result resource throws requests.ConnectionError: DNS failure, refused connection, TLS handshake failure, or a dropped connection. It fires before any status check; the chained exception carries the underlying cause.

Source

Thrown at paddleocr/_api_client/_resources.py:52

) -> str:
    if not resource_url:
        raise InvalidRequestError("resource_url is required.")
    if not destination:
        raise InvalidRequestError("destination is required.")

    parsed_url = urlparse(resource_url)
    if parsed_url.scheme not in ("http", "https") or not parsed_url.netloc:
        raise InvalidRequestError(f"Invalid resource URL: {resource_url}")

    target = _resolve_destination(parsed_url.path, destination, filename)
    _require_writable_target(target, overwrite)

    try:
        response = requests.get(resource_url, timeout=timeout)
    except requests.Timeout as e:
        raise RequestTimeoutError(f"Request timed out: {e}") from e
    except requests.ConnectionError as e:
        raise NetworkError(f"Connection failed: {e}") from e

    try:
        response.raise_for_status()
    except requests.RequestException as e:
        raise NetworkError(f"Failed to download resource: {e}") from e

    _atomic_write(target, response.content, overwrite)
    return str(target)


def save_ocr_result_resources(
    result: OCRResult,
    destination: str,
    *,
    overwrite: bool = False,
    timeout: float = 300.0,
) -> List[str]:
    if result is None:

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Verify reachability: curl the resource URL from the same machine/network
2. If the host is internal, run the client inside the network/VPN or mirror the artifacts to a reachable host
3. For TLS issues, install the proxy/inspection CA into the client environment's trust store
4. Retry with backoff for transient resets (connection issues are often intermittent)

Example fix

# before
for url in urls:
    save_resource(url, dest)  # first reset kills the batch

# after
for url in urls:
    for attempt in range(3):
        try:
            save_resource(url, dest); break
        except NetworkError:
            if attempt == 2: raise
            time.sleep(2 ** attempt)

import socket
socket.gethostbyname(urlparse(url).hostname)  # pre-flight DNS check

for attempt in range(3):
    try:
        save_resource(url, dest)
        break
    except NetworkError as e:
        if attempt == 2 or 'Connection failed' not in str(e): raise
        time.sleep(2 ** attempt)

When it happens

Trigger: save_resource with a result URL whose host does not resolve, is unreachable from the client network, uses a certificate the client rejects, or where the connection is reset mid-download (requests maps reset-after-connect to ConnectionError).

Common situations: Result URLs pointing at an internal host not reachable from where the client runs (VPN split-tunnel); expired DNS for ephemeral result-storage domains; corporate TLS inspection breaking the handshake; result storage service briefly down.

Related errors

• Unsafe resource filename: ${key}
• Either fileUrl or filePath is required.
• OCR result page is missing prunedResult.
• Document parsing result page is missing markdown.text.
• Model ${model} is not an OCR model.

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