opendatalab/MinerU · error · ValueError

Unsupported repo_mode: {repo_mode}, must be 'pipeline' or 'v

Error message

Unsupported repo_mode: {repo_mode}, must be 'pipeline' or 'vlm'

What it means

Raised in the model snapshot-download helper when the repo_mode argument is neither 'pipeline' nor 'vlm'. repo_mode selects which Hugging Face / ModelScope repository layout to download from (pipeline models vs. the VLM whole-repo), so any other string cannot be mapped to a repository. The value usually comes from a caller-supplied parameter defaulting to 'pipeline'.

Source

Thrown at mineru/utils/models_download_utils.py:272

def _snapshot_download_cached(model_source: str, repo_mode: str, repo: str, relative_path: str) -> str:
    """按进程缓存远端 snapshot_download 结果，减少重复缓存检查和 Fetching 日志。"""
    if model_source == "huggingface":
        snapshot_download = hf_snapshot_download
    elif model_source == "modelscope":
        snapshot_download = ms_snapshot_download
    else:
        raise ValueError(f"未知的仓库类型: {model_source}")

    if repo_mode == 'pipeline':
        cache_dir = snapshot_download(repo, allow_patterns=[relative_path, relative_path + "/*"])
    elif repo_mode == 'vlm':
        # VLM 整仓下载和局部路径下载都参与缓存，但保持原有 allow_patterns 行为。
        if relative_path == "/":
            cache_dir = snapshot_download(repo)
        else:
            cache_dir = snapshot_download(repo, allow_patterns=[relative_path, relative_path + "/*"])
    else:
        raise ValueError(f"Unsupported repo_mode: {repo_mode}, must be 'pipeline' or 'vlm'")

    if cache_dir:
        persist_downloaded_model_config(model_source, repo_mode, cache_dir)
    return cache_dir


def auto_download_and_get_model_root_path(relative_path: str, repo_mode='pipeline') -> str:
    """
    支持文件或目录的可靠下载。
    - 如果输入文件: 返回本地文件绝对路径
    - 如果输入目录: 返回本地缓存下与 relative_path 同结构的相对路径字符串
    :param repo_mode: 指定仓库模式，'pipeline' 或 'vlm'
    :param relative_path: 文件或目录相对路径
    :return: 本地文件绝对路径或相对路径
    """
    model_source = resolve_model_source()

    if model_source == 'local':

View on GitHub (pinned to 4fe4bde114)

Solutions

Pass exactly 'pipeline' or 'vlm' (lowercase) as repo_mode.
If the value comes from a user/config field, normalize it before calling: value.strip().lower() and validate against {'pipeline', 'vlm'} with an early, clear error.
Check the calling code — if you intended the VLM backend, the download layer wants the literal 'vlm', not a backend identifier.

Example fix

# before
root = auto_download_and_get_model_root_path('models/README.md', repo_mode='VLM')

# after
root = auto_download_and_get_model_root_path('models/README.md', repo_mode='vlm')

Defensive patterns

Strategy: type-guard

Validate before calling

REPO_MODES = {'pipeline', 'vlm'}
mode = 'vlm'
assert mode in REPO_MODES, f'repo_mode must be one of {REPO_MODES}'

Type guard

def is_repo_mode(value: object) -> bool:
    return isinstance(value, str) and value in {'pipeline', 'vlm'}

Try / catch

try:
    cache = download_model(path, repo_mode=mode)
except ValueError as e:
    if 'Unsupported repo_mode' in str(e):
        raise SystemExit(f'Bad repo_mode {mode!r}; use pipeline or vlm') from e
    raise

Prevention

Centralize repo_mode as an Enum/Literal in your wrapper instead of passing raw strings.
Normalize external inputs (strip().lower()) and validate against {'pipeline','vlm'} at the API boundary.

When it happens

Trigger: Calling auto_download_and_get_model_root_path(relative_path, repo_mode=...) — or the internal snapshot download helper — with a typo or third value such as 'VLM', 'pipelines', 'backend', or None.

Common situations: A caller passes a backend name intended for a different API (e.g. 'vlm-engine' or 'vlm-transformers') where the plain 'vlm' is expected; case or pluralization typos; passing a variable that is None after a failed lookup upstream.

Related errors

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