{"record":{"id":"6a554b45ac739326","repo":"opendatalab/MinerU","slug":"local-path-for-repo-mode-repo-mode-is-not-conf","errorCode":null,"errorMessage":"Local path for repo_mode '{repo_mode}' is not configured.","messagePattern":"Local path for repo_mode '(.+?)' is not configured\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"mineru/utils/models_download_utils.py","lineNumber":294,"sourceCode":"    return cache_dir\n\n\ndef auto_download_and_get_model_root_path(relative_path: str, repo_mode='pipeline') -> str:\n    \"\"\"\n    支持文件或目录的可靠下载。\n    - 如果输入文件: 返回本地文件绝对路径\n    - 如果输入目录: 返回本地缓存下与 relative_path 同结构的相对路径字符串\n    :param repo_mode: 指定仓库模式，'pipeline' 或 'vlm'\n    :param relative_path: 文件或目录相对路径\n    :return: 本地文件绝对路径或相对路径\n    \"\"\"\n    model_source = resolve_model_source()\n\n    if model_source == 'local':\n        local_models_config = get_local_models_dir()\n        root_path = local_models_config.get(repo_mode, None)\n        if not root_path:\n            raise ValueError(f\"Local path for repo_mode '{repo_mode}' is not configured.\")\n        return root_path\n\n    # 建立仓库模式到路径的映射\n    repo_mapping = {\n        'pipeline': {\n            'huggingface': ModelPath.pipeline_root_hf,\n            'modelscope': ModelPath.pipeline_root_modelscope\n        },\n        'vlm': {\n            'huggingface': ModelPath.vlm_root_hf,\n            'modelscope': ModelPath.vlm_root_modelscope\n        }\n    }\n\n    if repo_mode not in repo_mapping:\n        raise ValueError(f\"Unsupported repo_mode: {repo_mode}, must be 'pipeline' or 'vlm'\")\n\n    # model_source 已解析为实际远端来源后，再选择对应仓库。","sourceCodeStart":276,"sourceCodeEnd":312,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/utils/models_download_utils.py#L276-L312","documentation":"Raised by auto_download_and_get_model_root_path() when the resolved model source is 'local' but the config's local-models directory mapping has no entry for the requested repo_mode. With model-source local, MineRU never downloads; it reads pre-downloaded model trees from a config section (via get_local_models_dir()) keyed by 'pipeline' and 'vlm'. A missing key means the deployment told MineRU to use local models without saying where they are.","triggerScenarios":"Setting MINERU_MODEL_SOURCE=local (or model-source: local in config) without configuring local_models_dir / the models-dir mapping for the mode being used — e.g. only 'pipeline' is configured but a VLM parse path requests repo_mode='vlm'.","commonSituations":"Air-gapped or offline deployments that preload models onto disk but copy an incomplete config; enabling local source to avoid network calls while forgetting the vlm entry; the models were downloaded under a different user/home so the config was never written.","solutions":["Add the missing mapping to the config so both modes you use point at real directories: {\"models-dir\": {\"pipeline\": \"/data/models/pipeline\", \"vlm\": \"/data/models/vlm\"}} (adjust keys to your MineRU version's models-dir schema).","Verify the directories actually contain the model files for that mode (layout mirrors the Hugging Face snapshot structure).","Alternatively download once with a remote source (modelsource/huggingface) so MineRU populates its config, then switch to local.","Confirm MINERU_MODEL_SOURCE=local is intentional — if network access exists, unsetting it removes the local-config requirement."],"exampleFix":"// before\nexport MINERU_MODEL_SOURCE=local\n// mineru.json has no \"models-dir\" (or only pipeline) entry\n\n// after\n// mineru.json\n\"models-dir\": {\n  \"pipeline\": \"/data/models/pipeline\",\n  \"vlm\": \"/data/models/vlm\"\n}","handlingStrategy":"validation","validationCode":"import json, os\ncfg = json.load(open(os.path.expanduser('~/mineru.json')))\nmodels_dir = cfg.get('models-dir', {})\nneeded = {'pipeline'}  # add 'vlm' if you use the vlm backend\nmissing = needed - set(models_dir)\nassert not missing, f'models-dir missing entries for: {missing} while using local model source'","typeGuard":"def local_paths_configured(cfg: dict, modes: set[str]) -> bool:\n    md = cfg.get('models-dir') or {}\n    return all(isinstance(md.get(m), str) and os.path.isdir(md[m]) for m in modes)","tryCatchPattern":"try:\n    root = auto_download_and_get_model_root_path(rel, repo_mode='vlm')\nexcept ValueError as e:\n    if 'not configured' in str(e):\n        raise SystemExit('model-source=local but models-dir[vlm] missing in mineru.json') from e\n    raise","preventionTips":["When running offline, preflight-check that models-dir contains an entry (and real directory) for every backend you will start.","Pre-download models once on a connected machine and ship the cache plus config together.","Keep the models-dir mapping and the MINERU_MODEL_SOURCE value in the same deployment unit so they cannot drift."],"tags":["config","model-download","offline","mineru"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}