{"record":{"id":"319c8e63ed65a931","repo":"PaddlePaddle/PaddleOCR","slug":"download-from-failed-retry-limit-reached","errorCode":null,"errorMessage":"Download from {} failed. Retry limit reached","messagePattern":"Download from (.+?) failed\\. Retry limit reached","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"ppocr/utils/network.py","lineNumber":65,"sourceCode":"\n\ndef _download(url, save_path):\n    \"\"\"\n    Download from url, save to path.\n\n    url (str): download url\n    save_path (str): download to given path\n    \"\"\"\n    logger = get_logger()\n\n    fname = osp.split(url)[-1]\n    retry_cnt = 0\n\n    while not osp.exists(save_path):\n        if retry_cnt < DOWNLOAD_RETRY_LIMIT:\n            retry_cnt += 1\n        else:\n            raise RuntimeError(\n                \"Download from {} failed. \" \"Retry limit reached\".format(url)\n            )\n\n        try:\n            req = requests.get(url, stream=True)\n        except Exception as e:  # requests.exceptions.ConnectionError\n            logger.info(\n                \"Downloading {} from {} failed {} times with exception {}\".format(\n                    fname, url, retry_cnt + 1, str(e)\n                )\n            )\n            time.sleep(1)\n            continue\n\n        if req.status_code != 200:\n            raise RuntimeError(\n                \"Downloading from {} failed with code \"\n                \"{}!\".format(url, req.status_code)","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/ppocr/utils/network.py#L47-L83","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix connectivity first: verify the URL with curl -L -O <url>; configure HTTPS_PROXY/HTTP_PROXY if behind a proxy.","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.","Retry the command later if the host outage is transient.","As a last resort, raise DOWNLOAD_RETRY_LIMIT in ppocr/utils/network.py for flaky links."],"exampleFix":"# manual pre-download so the helper's `while not osp.exists(save_path)` short-circuits\nwget https://paddleocr.bj.bcebos.com/pretrained/MobileNetV3_large_x0_5_pretrained.tar -P ~/.paddleocr/whl/det/","handlingStrategy":"retry","validationCode":"import os, requests\n\ndef url_reachable(url, timeout=10) -> bool:\n    try:\n        return requests.head(url, timeout=timeout, allow_redirects=True).status_code == 200\n    except requests.RequestException:\n        return False\n\n# skip the helper entirely when the artifact already exists\nif not os.path.exists(save_path):\n    assert url_reachable(url), f'{url} unreachable; check network/proxy or pre-place {save_path}'","typeGuard":null,"tryCatchPattern":"for attempt in range(5):\n    try:\n        download(url, save_path)\n        break\n    except RuntimeError as e:\n        if 'Retry limit reached' not in str(e) or attempt == 4:\n            raise\n        time.sleep(2 ** attempt)  # then retry with backoff","preventionTips":["Pre-download required models/dicts into the expected save_path on connected machines and ship them with the deployment.","Set HTTPS_PROXY/HTTP_PROXY in proxied environments before starting training.","Run a connectivity smoke test (requests.head on the model URL) at job start."],"tags":["network","download","pretrained-model","retry"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}