opendatalab/MinerU · error · ValueError

Invalid backend. Allowed values: {allowed_values}

Error message

Invalid backend. Allowed values: {allowed_values}

What it means

ValueError from normalize_backend(): after applying LEGACY_BACKEND_ALIASES (vlm-auto-engine->vlm-engine, hybrid-auto-engine->hybrid-engine), the backend string must be in PUBLIC_BACKEND_CHOICES (pipeline, vlm-engine, hybrid-engine, vlm-http-client, hybrid-http-client). This is the single canonical validator shared by CLI and API paths.

Source

Thrown at mineru/cli/backend_options.py:44

    "vlm-auto-engine": BACKEND_VLM_ENGINE,
    "hybrid-auto-engine": BACKEND_HYBRID_ENGINE,
}


def get_backend_choices(include_http_client: bool = True) -> list[str]:
    """按入口配置返回公开 backend 选项，避免各入口重复维护字符串列表。"""
    choices = list(LOCAL_BACKEND_CHOICES)
    if include_http_client:
        choices.extend(HTTP_CLIENT_BACKEND_CHOICES)
    return choices


def normalize_backend(backend: str) -> str:
    """将旧 backend 别名规范为当前公开名称，并校验最终名称是否合法。"""
    normalized_backend = LEGACY_BACKEND_ALIASES.get(backend, backend)
    if normalized_backend not in PUBLIC_BACKEND_CHOICES:
        allowed_values = ", ".join(PUBLIC_BACKEND_CHOICES)
        raise ValueError(f"Invalid backend. Allowed values: {allowed_values}")
    return normalized_backend


def validate_backend(backend: str) -> str:
    """校验公开入口允许的 backend 名称，并返回规范后的后端名称。"""
    return normalize_backend(backend)


def validate_effort(effort: str) -> str:
    """校验公开 hybrid effort 参数，并返回规范后的 effort 名称。"""
    if effort not in HYBRID_EFFORT_CHOICES:
        allowed_values = ", ".join(HYBRID_EFFORT_CHOICES)
        raise ValueError(f"Invalid effort. Allowed values: {allowed_values}")
    return effort

View on GitHub (pinned to 4fe4bde114)

Solutions

1. Use one of the five public names: pipeline, vlm-engine, hybrid-engine, vlm-http-client, hybrid-http-client
2. Legacy aliases vlm-auto-engine/hybrid-auto-engine still work — migrate anyway
3. Validate early in your script with validate_backend() before dispatching
4. Print get_backend_choices() to see the accepted list for your installed version

Example fix

# before
mineru -p doc.pdf -b vlm

# after
mineru -p doc.pdf -b vlm-engine

from mineru.cli.backend_options import validate_backend, get_backend_choices

try:
    backend = validate_backend(args.backend)
except ValueError as e:
    raise SystemExit(f"{e}\nAvailable backends: {', '.join(get_backend_choices())}") from e

from mineru.cli.backend_options import PUBLIC_BACKEND_CHOICES

def is_valid_backend(v: str) -> bool:
    return isinstance(v, str) and v in PUBLIC_BACKEND_CHOICES

When it happens

Trigger: Calling CLI commands with -b vlm, -b torch, -b auto, or passing such strings programmatically to validate_backend()/normalize_backend().

Common situations: Old tutorials referencing pre-rename backend names; shell completion or scripts defaulting to a stale value; users abbreviating 'vlm-engine' to 'vlm'.

Related errors

• backend={backend} requires server_url
• effort must be "medium" or "high"
• Unsupported lmdeploy device type: {device_type}
• Unsupported lmdeploy backend: {lm_backend}
• Invalid backend. Allowed values: {allowed_values}

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