{"record":{"id":"840001b9a42db127","repo":"opendatalab/MinerU","slug":"backend-requires-local-pipeline-dependencies","errorCode":null,"errorMessage":"`{backend}` requires local pipeline dependencies (`mineru[pipeline]`, including `torch`). Install `mineru[pipeline]` or `mineru[core]`. If you need a lightweight remote client without local `torch`, use `vlm-http-client` instead.","messagePattern":"`(.+?)` requires local pipeline dependencies \\(`mineru\\[pipeline\\]`, including `torch`\\)\\. Install `mineru\\[pipeline\\]` or `mineru\\[core\\]`\\. If you need a lightweight remote client without local `torch`, use `vlm-http-client` instead\\.","errorType":"exception","errorClass":"HybridDependencyError","httpStatus":null,"severity":"error","filePath":"mineru/cli/common.py","lineNumber":73,"sourceCode":"\nclass HybridDependencyError(RuntimeError):\n    pass\n\n\ndef build_hybrid_dependency_error_message(backend: str) -> str:\n    return (\n        f\"`{backend}` requires local pipeline dependencies (`mineru[pipeline]`, \"\n        \"including `torch`). Install `mineru[pipeline]` or `mineru[core]`. \"\n        \"If you need a lightweight remote client without local `torch`, \"\n        \"use `vlm-http-client` instead.\"\n    )\n\n\ndef ensure_backend_dependencies(backend: str) -> None:\n    if not backend.startswith(\"hybrid-\"):\n        return\n    if importlib.util.find_spec(\"torch\") is None:\n        raise HybridDependencyError(build_hybrid_dependency_error_message(backend))\n\n\ndef _load_hybrid_analyze_entrypoint(entrypoint_name: str, backend: str):\n    \"\"\"加载统一 hybrid analyze 入口，解析强度由公开 effort 参数控制。\"\"\"\n    ensure_backend_dependencies(backend)\n    module_name = \"mineru.backend.hybrid.hybrid_analyze\"\n    try:\n        hybrid_analyze = importlib.import_module(module_name)\n    except (ImportError, ModuleNotFoundError) as exc:\n        raise HybridDependencyError(\n            build_hybrid_dependency_error_message(backend)\n        ) from exc\n    return getattr(hybrid_analyze, entrypoint_name)\n\n\ndef utf8_byte_length(value: str) -> int:\n    return len(value.encode(\"utf-8\"))\n","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/cli/common.py#L55-L91","documentation":"HybridDependencyError raised by ensure_backend_dependencies(): any backend starting with 'hybrid-' requires local pipeline dependencies (torch et al., the mineru[pipeline] extra). The check is a lightweight importlib.util.find_spec('torch') probe, so a missing torch install fails fast with an actionable install hint instead of a confusing deep ImportError.","triggerScenarios":"Running hybrid-engine (or any 'hybrid-*' backend) in a slim install (pip install mineru without extras) where torch is absent; slim Docker images; CI environments that deliberately exclude torch to keep images small.","commonSituations":"Installing the lightweight client wheel for vlm-http-client usage and then switching to hybrid-engine; CI images trimmed of torch; venvs created for the API client only.","solutions":["pip install 'mineru[pipeline]' or 'mineru[core]' to pull torch and pipeline deps","If you intentionally run without torch, use vlm-http-client / hybrid-http-client against a remote server instead of a local hybrid-engine","Verify with python -c \"import importlib.util; print(importlib.util.find_spec('torch'))\"","In Docker, base the image on a variant that includes the pipeline extra"],"exampleFix":"# before\npip install mineru\nmineru -p doc.pdf -b hybrid-engine  # HybridDependencyError\n\n# after\npip install 'mineru[pipeline]'\nmineru -p doc.pdf -b hybrid-engine","handlingStrategy":"type-guard","validationCode":"import importlib.util\n\nif backend.startswith(\"hybrid-\") and importlib.util.find_spec(\"torch\") is None:\n    raise SystemExit(\n        f\"{backend} needs torch locally. Install mineru[pipeline], or switch to \"\n        \"hybrid-http-client for a remote, torch-free setup.\"\n    )","typeGuard":"def can_run_hybrid_locally() -> bool:\n    import importlib.util\n    return importlib.util.find_spec(\"torch\") is not None","tryCatchPattern":"try:\n    run_hybrid(...)\nexcept HybridDependencyError:\n    # either install mineru[pipeline] or transparently switch to the remote client\n    run_hybrid_via_http_client(...)","preventionTips":["Install the right extra up front: mineru[pipeline] (or mineru[core]) for local hybrid-engine","Use *-http-client backends in slim/CI images that cannot carry torch","Fail fast at startup with a find_spec('torch') check when backend starts with 'hybrid-'"],"tags":["dependencies","hybrid","torch","installation"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}