opendatalab/MinerU · error · HTTPException

Invalid backend. Allowed values: {allowed_values}

Error message

Invalid backend. Allowed values: {allowed_values}

What it means

HTTP 400 raised by validate_parse_backend() on the API server: the backend form value is normalized through validate_public_backend (LEGACY_BACKEND_ALIASES applied) and must end up in PUBLIC_BACKEND_CHOICES = (pipeline, vlm-engine, hybrid-engine, vlm-http-client, hybrid-http-client). This mirrors the CLI-side check in backend_options.py so no legacy backend name reaches the execution chain.

Source

Thrown at mineru/cli/api_request.py:73

def validate_parse_method(parse_method: str) -> str:
    """校验公开 API 允许的 PDF 解析方式，避免各入口维护不同规则。"""
    if parse_method not in ALLOWED_PARSE_METHODS:
        raise HTTPException(
            status_code=400,
            detail=(
                "Invalid parse_method. Allowed values: "
                + ", ".join(sorted(ALLOWED_PARSE_METHODS))
            ),
        )
    return parse_method


def validate_parse_backend(backend: str) -> str:
    """校验公开 API 允许的解析后端，避免旧入口名进入下游执行链路。"""
    try:
        return validate_public_backend(backend)
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc


def validate_parse_effort(effort: str) -> str:
    """校验公开 API 允许的 hybrid effort，避免非法值进入解析链路。"""
    try:
        return validate_public_effort(effort)
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc


def validate_parse_lang_list(lang_list: list[str]) -> list[str]:
    """校验公开 API 允许的 OCR 语言列表，避免旧语言入口进入解析链路。"""
    try:
        return validate_public_ocr_lang_list(lang_list)
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc

View on GitHub (pinned to 4fe4bde114)

Solutions

1. Use one of: pipeline, vlm-engine, hybrid-engine, vlm-http-client, hybrid-http-client
2. Legacy aliases vlm-auto-engine and hybrid-auto-engine are still accepted — but migrate to the new names
3. Do not put parse_method values (auto/txt/ocr) into the backend field
4. Verify against the server's /docs schema enum

Example fix

# before
requests.post(url, files=files, data={'backend': 'vlm'})

# after
requests.post(url, files=files, data={'backend': 'vlm-engine'})

from mineru.cli.backend_options import PUBLIC_BACKEND_CHOICES, validate_backend

backend = validate_backend(backend)  # raises ValueError with the allowed list

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 or v in {
        "vlm-auto-engine", "hybrid-auto-engine",
    })

try:
    resp = requests.post(url, files=files, data={"backend": backend}, timeout=60)
    resp.raise_for_status()
except requests.HTTPError as e:
    if e.response.status_code == 400 and "backend" in e.response.text:
        backend = "hybrid-engine"  # safe default; retry once
    else:
        raise

When it happens

Trigger: POSTing a parse request with backend='vlm', 'hybrid', 'vlm-auto-engine' (actually aliased and OK), 'torch', or any string not in the five public choices.

Common situations: Older mineru releases used short names like 'vlm'/'pipeline-backend'; users mixing up parse_method and backend values; renamed constants after upgrades (e.g. vlm-auto-engine -> vlm-engine, which the alias map still accepts).

Related errors

• Invalid parse_method. Allowed values: {allowed_values}
• Invalid effort. Allowed values: {allowed_values}
• Language {lang} not supported. Allowed values: {allowed_valu
• Invalid backend. Allowed values: {allowed_values}
• Unsupported lmdeploy backend: {lm_backend}

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