PaddlePaddle/PaddleOCR · error · RequestTimeoutError

Request timed out: {e}

Error message

Request timed out: {e}

What it means

RequestTimeoutError raised when the underlying requests.get(resource_url, timeout=...) raises requests.Timeout while downloading a result resource. The default timeout is 300 seconds (connect+read applied per blocking operation by requests).

Source

Thrown at paddleocr/_api_client/_resources.py:50

    filename: Optional[str] = None,
    timeout: float = 300.0,
) -> 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,

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Increase the timeout argument (save_resource(..., timeout=900)) for large files
2. Retry the download — transient stalls often succeed on a second attempt
3. Check file size first (HEAD request) and scale the timeout to expected size
4. If downloads consistently stall, diagnose network path (proxy, MTU, server throughput)

Example fix

# before
save_resource(url, dest)  # default timeout=300.0

# after
save_resource(url, dest, timeout=900.0)

size = int(requests.head(url, timeout=30).headers.get('content-length', 0))
timeout = max(300, size / 100_000)  # scale with bytes, ~100KB/s floor

for attempt in range(3):
    try:
        save_resource(url, dest, timeout=900)
        break
    except RequestTimeoutError:
        if attempt == 2: raise
        time.sleep(2 ** attempt)

When it happens

Trigger: save_resource downloading a large OCR result image over a slow link so a single blocking read exceeds the timeout; or the server stalls mid-transfer. Note: requests' timeout is per-socket-operation, not total transfer time, so slow-but-flowing transfers can still succeed while stalled transfers raise.

Common situations: Downloading high-resolution OCR page images (tens of MB) on constrained bandwidth; server under heavy load stalling reads; timeout left at a default too small for big artifacts; proxies adding latency.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• OCR result item is missing result.ocrResults.
• Document parsing result item is missing result.layoutParsing
• Job ${job.jobId} is a ${job.task} job, not a ${expectedTask}
• Unsafe resource filename: ${key}
• Request timed out after ${timeoutMs}ms

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