{"record":{"id":"47a646a6693e5bd9","repo":"opendatalab/MinerU","slug":"failed-to-download-model-relative-path-from-re","errorCode":null,"errorMessage":"Failed to download model: {relative_path} from {repo}","messagePattern":"Failed to download model: (.+?) from (.+?)","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"mineru/utils/models_download_utils.py","lineNumber":323,"sourceCode":"            'modelscope': ModelPath.vlm_root_modelscope\n        }\n    }\n\n    if repo_mode not in repo_mapping:\n        raise ValueError(f\"Unsupported repo_mode: {repo_mode}, must be 'pipeline' or 'vlm'\")\n\n    # model_source 已解析为实际远端来源后，再选择对应仓库。\n    repo = repo_mapping[repo_mode][model_source]\n\n    relative_path = normalize_download_relative_path(relative_path, repo_mode)\n    configured_model_root = get_existing_configured_model_root(repo_mode, relative_path)\n    if configured_model_root is not None:\n        return configured_model_root\n\n    cache_dir = _snapshot_download_cached(model_source, repo_mode, repo, relative_path)\n\n    if not cache_dir:\n        raise FileNotFoundError(f\"Failed to download model: {relative_path} from {repo}\")\n    return cache_dir\n\n\nif __name__ == '__main__':\n    path1 = \"models/README.md\"\n    root = auto_download_and_get_model_root_path(path1)\n    print(\"本地文件绝对路径:\", os.path.join(root, path1))\n","sourceCodeStart":305,"sourceCodeEnd":331,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/utils/models_download_utils.py#L305-L331","documentation":"FileNotFoundError raised by auto_download_and_get_model_root_path() when _snapshot_download_cached() returns a falsy cache_dir after attempting a snapshot_download from the selected repository (e.g. ModelPath.pipeline_root_modelscope / _hf or the VLM repos). It means MineRU tried to fetch relative_path from the repo and got no local cache directory back — the model files are not on disk and the download did not succeed (network failure, missing repo/path, or a download that produced nothing matching the allow_patterns).","triggerScenarios":"First use of a model whose files are not cached, with the download failing: no network route to huggingface.co or modelscope.cn, a nonexistent relative_path (typo like 'models/READ.md'), the repo moved/renamed, or proxy/SSL errors swallowed by the cached download wrapper.","commonSituations":"Offline or firewalled environments where huggingface.co is unreachable (common in CN networks — modelscope is the fallback); a stale model-source config pinned to huggingface; typo'd relative paths in custom model code; disk-full or permission errors inside the HF cache dir causing an empty snapshot.","solutions":["Check basic connectivity to the configured source (curl https://huggingface.co or https://www.modelscope.cn) and switch source if blocked: export MINERU_MODEL_SOURCE=modelscope (or huggingface) to skip auto-detection that may have persisted the wrong mirror.","Verify the relative_path exactly matches a path inside the repository (case-sensitive); test with a known-good path like 'models/README.md'.","Set HTTPS_PROXY/HTTP_PROXY if a corporate proxy is required; HF and ModelScope both honor them.","If the cache is corrupted (partial snapshot from an earlier failed run), clear the model cache directory and retry so snapshot_download starts clean.","For air-gapped hosts, pre-download on a connected machine and configure model-source local with models-dir mappings."],"exampleFix":"# before\nexport MINERU_MODEL_SOURCE=huggingface  # unreachable behind firewall\nroot = auto_download_and_get_model_root_path('models/README.md')  # FileNotFoundError\n\n# after\nexport MINERU_MODEL_SOURCE=modelscope\nroot = auto_download_and_get_model_root_path('models/README.md')","handlingStrategy":"retry","validationCode":"import socket, urllib.request\n\ndef source_reachable(url: str, timeout: float = 5.0) -> bool:\n    try:\n        urllib.request.urlopen(url, timeout=timeout)\n        return True\n    except Exception:\n        return False\n\n# before a long batch job:\nsrc = os.getenv('MINERU_MODEL_SOURCE', 'auto')\nif src == 'huggingface' and not source_reachable('https://huggingface.co'):\n    raise SystemExit('huggingface.co unreachable; export MINERU_MODEL_SOURCE=modelscope')","typeGuard":"def model_cached(root_attempt: str | None) -> bool:\n    return isinstance(root_attempt, str) and bool(root_attempt)","tryCatchPattern":"import time\nfor attempt, delay in enumerate([0, 10, 60], 1):\n    try:\n        root = auto_download_and_get_model_root_path(rel, repo_mode=mode)\n        break\n    except FileNotFoundError as e:\n        if attempt == 3:\n            raise SystemExit(f'Model download failed after retries: {e}') from e\n        time.sleep(delay)  # transient network/proxy blips only; fix config if deterministic","preventionTips":["Warm the model cache during image build / deployment (run one download) so runtime never needs the network.","Pin MINERU_MODEL_SOURCE to the mirror your network can reach instead of relying on auto-detection persistence.","Pre-flight connectivity to the chosen source before starting batch jobs; fail fast with an actionable message.","Keep the HF/modelscope cache on durable, writable storage with enough free space."],"tags":["model-download","network","huggingface","modelscope","mineru"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}