{"record":{"id":"d602767941f43aba","repo":"opendatalab/MinerU","slug":"invalid-backend-allowed-values-allowed-values-d60276","errorCode":null,"errorMessage":"Invalid backend. Allowed values: {allowed_values}","messagePattern":"Invalid backend\\. Allowed values: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"mineru/cli/backend_options.py","lineNumber":44,"sourceCode":"    \"vlm-auto-engine\": BACKEND_VLM_ENGINE,\n    \"hybrid-auto-engine\": BACKEND_HYBRID_ENGINE,\n}\n\n\ndef get_backend_choices(include_http_client: bool = True) -> list[str]:\n    \"\"\"按入口配置返回公开 backend 选项，避免各入口重复维护字符串列表。\"\"\"\n    choices = list(LOCAL_BACKEND_CHOICES)\n    if include_http_client:\n        choices.extend(HTTP_CLIENT_BACKEND_CHOICES)\n    return choices\n\n\ndef normalize_backend(backend: str) -> str:\n    \"\"\"将旧 backend 别名规范为当前公开名称，并校验最终名称是否合法。\"\"\"\n    normalized_backend = LEGACY_BACKEND_ALIASES.get(backend, backend)\n    if normalized_backend not in PUBLIC_BACKEND_CHOICES:\n        allowed_values = \", \".join(PUBLIC_BACKEND_CHOICES)\n        raise ValueError(f\"Invalid backend. Allowed values: {allowed_values}\")\n    return normalized_backend\n\n\ndef validate_backend(backend: str) -> str:\n    \"\"\"校验公开入口允许的 backend 名称，并返回规范后的后端名称。\"\"\"\n    return normalize_backend(backend)\n\n\ndef validate_effort(effort: str) -> str:\n    \"\"\"校验公开 hybrid effort 参数，并返回规范后的 effort 名称。\"\"\"\n    if effort not in HYBRID_EFFORT_CHOICES:\n        allowed_values = \", \".join(HYBRID_EFFORT_CHOICES)\n        raise ValueError(f\"Invalid effort. Allowed values: {allowed_values}\")\n    return effort\n","sourceCodeStart":26,"sourceCodeEnd":59,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/cli/backend_options.py#L26-L59","documentation":"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.","triggerScenarios":"Calling CLI commands with -b vlm, -b torch, -b auto, or passing such strings programmatically to validate_backend()/normalize_backend().","commonSituations":"Old tutorials referencing pre-rename backend names; shell completion or scripts defaulting to a stale value; users abbreviating 'vlm-engine' to 'vlm'.","solutions":["Use one of the five public names: pipeline, vlm-engine, hybrid-engine, vlm-http-client, hybrid-http-client","Legacy aliases vlm-auto-engine/hybrid-auto-engine still work — migrate anyway","Validate early in your script with validate_backend() before dispatching","Print get_backend_choices() to see the accepted list for your installed version"],"exampleFix":"# before\nmineru -p doc.pdf -b vlm\n\n# after\nmineru -p doc.pdf -b vlm-engine","handlingStrategy":"validation","validationCode":"from mineru.cli.backend_options import validate_backend, get_backend_choices\n\ntry:\n    backend = validate_backend(args.backend)\nexcept ValueError as e:\n    raise SystemExit(f\"{e}\\nAvailable backends: {', '.join(get_backend_choices())}\") from e","typeGuard":"from mineru.cli.backend_options import PUBLIC_BACKEND_CHOICES\n\ndef is_valid_backend(v: str) -> bool:\n    return isinstance(v, str) and v in PUBLIC_BACKEND_CHOICES","tryCatchPattern":null,"preventionTips":["Validate -b/--backend right after arg parsing with validate_backend","Use get_backend_choices() to build the CLI choices list so invalid values fail at argparse time","Add a deprecation warning when legacy aliases are used"],"tags":["cli","validation","backend","configuration"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}