PaddlePaddle/PaddleOCR · error · RuntimeError

Download from {} failed. Retry limit reached

Error message

Download from {} failed. Retry limit reached

What it means

RuntimeError from ppocr.utils.network's download helper after DOWNLOAD_RETRY_LIMIT consecutive failed attempts to fetch a URL (each attempt either raised a requests exception, e.g. connection error/DNS failure/proxy refusal, or was interrupted so save_path never appeared). The loop only exits successfully when the file exists at save_path.

Source

Thrown at ppocr/utils/network.py:65

def _download(url, save_path):
    """
    Download from url, save to path.

    url (str): download url
    save_path (str): download to given path
    """
    logger = get_logger()

    fname = osp.split(url)[-1]
    retry_cnt = 0

    while not osp.exists(save_path):
        if retry_cnt < DOWNLOAD_RETRY_LIMIT:
            retry_cnt += 1
        else:
            raise RuntimeError(
                "Download from {} failed. " "Retry limit reached".format(url)
            )

        try:
            req = requests.get(url, stream=True)
        except Exception as e:  # requests.exceptions.ConnectionError
            logger.info(
                "Downloading {} from {} failed {} times with exception {}".format(
                    fname, url, retry_cnt + 1, str(e)
                )
            )
            time.sleep(1)
            continue

        if req.status_code != 200:
            raise RuntimeError(
                "Downloading from {} failed with code "
                "{}!".format(url, req.status_code)

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Fix connectivity first: verify the URL with curl -L -O <url>; configure HTTPS_PROXY/HTTP_PROXY if behind a proxy.
2. Download the file manually on a connected machine and place it at save_path (the exact path in the error), so the helper skips downloading entirely.
3. Retry the command later if the host outage is transient.
4. As a last resort, raise DOWNLOAD_RETRY_LIMIT in ppocr/utils/network.py for flaky links.

Example fix

# manual pre-download so the helper's `while not osp.exists(save_path)` short-circuits
wget https://paddleocr.bj.bcebos.com/pretrained/MobileNetV3_large_x0_5_pretrained.tar -P ~/.paddleocr/whl/det/

import os, requests

def url_reachable(url, timeout=10) -> bool:
    try:
        return requests.head(url, timeout=timeout, allow_redirects=True).status_code == 200
    except requests.RequestException:
        return False

# skip the helper entirely when the artifact already exists
if not os.path.exists(save_path):
    assert url_reachable(url), f'{url} unreachable; check network/proxy or pre-place {save_path}'

for attempt in range(5):
    try:
        download(url, save_path)
        break
    except RuntimeError as e:
        if 'Retry limit reached' not in str(e) or attempt == 4:
            raise
        time.sleep(2 ** attempt)  # then retry with backoff

When it happens

Trigger: PaddleOCR auto-downloading a pretrained/finetuned model or dict file at startup while the network is unreachable, a proxy/SSL intercept blocks requests, or DNS for the model host fails; the retry counter is exhausted and the RuntimeError propagates.

Common situations: Training/inference behind corporate proxies or the GFW where paddle model hosts are slow/blocked; air-gapped machines; transient outages longer than the built-in retry budget.

Related errors

• Downloading from {} failed with code {}!
• Unsafe resource filename: ${key}
• Request timed out: {e}
• Connection failed: {e}
• Either fileUrl or filePath is required.

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