opendatalab/MinerU · error · FileNotFoundError

Failed to download model: {relative_path} from {repo}

Error message

Failed to download model: {relative_path} from {repo}

What it means

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).

Source

Thrown at mineru/utils/models_download_utils.py:323

            'modelscope': ModelPath.vlm_root_modelscope
        }
    }

    if repo_mode not in repo_mapping:
        raise ValueError(f"Unsupported repo_mode: {repo_mode}, must be 'pipeline' or 'vlm'")

    # model_source 已解析为实际远端来源后，再选择对应仓库。
    repo = repo_mapping[repo_mode][model_source]

    relative_path = normalize_download_relative_path(relative_path, repo_mode)
    configured_model_root = get_existing_configured_model_root(repo_mode, relative_path)
    if configured_model_root is not None:
        return configured_model_root

    cache_dir = _snapshot_download_cached(model_source, repo_mode, repo, relative_path)

    if not cache_dir:
        raise FileNotFoundError(f"Failed to download model: {relative_path} from {repo}")
    return cache_dir


if __name__ == '__main__':
    path1 = "models/README.md"
    root = auto_download_and_get_model_root_path(path1)
    print("本地文件绝对路径:", os.path.join(root, path1))

View on GitHub (pinned to 4fe4bde114)

Solutions

  1. 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.
  2. Verify the relative_path exactly matches a path inside the repository (case-sensitive); test with a known-good path like 'models/README.md'.
  3. Set HTTPS_PROXY/HTTP_PROXY if a corporate proxy is required; HF and ModelScope both honor them.
  4. If the cache is corrupted (partial snapshot from an earlier failed run), clear the model cache directory and retry so snapshot_download starts clean.
  5. For air-gapped hosts, pre-download on a connected machine and configure model-source local with models-dir mappings.

Example fix

# before
export MINERU_MODEL_SOURCE=huggingface  # unreachable behind firewall
root = auto_download_and_get_model_root_path('models/README.md')  # FileNotFoundError

# after
export MINERU_MODEL_SOURCE=modelscope
root = auto_download_and_get_model_root_path('models/README.md')
Defensive patterns

Strategy: retry

Validate before calling

import socket, urllib.request

def source_reachable(url: str, timeout: float = 5.0) -> bool:
    try:
        urllib.request.urlopen(url, timeout=timeout)
        return True
    except Exception:
        return False

# before a long batch job:
src = os.getenv('MINERU_MODEL_SOURCE', 'auto')
if src == 'huggingface' and not source_reachable('https://huggingface.co'):
    raise SystemExit('huggingface.co unreachable; export MINERU_MODEL_SOURCE=modelscope')

Type guard

def model_cached(root_attempt: str | None) -> bool:
    return isinstance(root_attempt, str) and bool(root_attempt)

Try / catch

import time
for attempt, delay in enumerate([0, 10, 60], 1):
    try:
        root = auto_download_and_get_model_root_path(rel, repo_mode=mode)
        break
    except FileNotFoundError as e:
        if attempt == 3:
            raise SystemExit(f'Model download failed after retries: {e}') from e
        time.sleep(delay)  # transient network/proxy blips only; fix config if deterministic

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of opendatalab/MinerU@4fe4bde114 (2026-08-14). Data as JSON: /api/errors/47a646a6693e5bd9. Report an issue: GitHub.