{"record":{"id":"a8cb78fb61606925","repo":"docling-project/docling","slug":"model-self-vlm-options-repo-id-not-found-in-ar-a8cb78","errorCode":null,"errorMessage":"Model '{self.vlm_options.repo_id}' not found in artifacts_path.\nExpected location: {artifacts_path / repo_cache_folder}\nAvailable models in {artifacts_path}: {', '.join(available_models) if available_models else 'none'}\n\nTo fix this issue:\n 1. Download the model: docling-tools models download-hf-repo {self.vlm_options.repo_id}\n 2. Or remove --artifacts-path to enable auto-download\n 3. Or use a different model that exists in your artifacts_path","messagePattern":"Model '(.+?)' not found in artifacts_path\\.\nExpected location: (.+?)\nAvailable models in (.+?): (.+?)\n\nTo fix this issue:\n 1\\. Download the model: docling-tools models download-hf-repo (.+?)\n 2\\. Or remove --artifacts-path to enable auto-download\n 3\\. Or use a different model that exists in your artifacts_path","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"docling/models/vlm_pipeline_models/vllm_model.py","lineNumber":144,"sourceCode":" _log.debug(f\"Available device for VLM: {self.device}\")\n\n # Resolve artifacts path / cache folder\n repo_cache_folder = vlm_options.repo_id.replace(\"/\", \"--\")\n if artifacts_path is None:\n artifacts_path = self.download_models(\n self.vlm_options.repo_id, revision=self.vlm_options.revision\n )\n elif (artifacts_path / repo_cache_folder).exists():\n artifacts_path = artifacts_path / repo_cache_folder\n else:\n # Model not found in artifacts_path - raise clear error\n available_models = []\n if artifacts_path.exists():\n available_models = [\n p.name for p in artifacts_path.iterdir() if p.is_dir()\n ]\n\n raise FileNotFoundError(\n f\"Model '{self.vlm_options.repo_id}' not found in artifacts_path.\\n\"\n f\"Expected location: {artifacts_path / repo_cache_folder}\\n\"\n f\"Available models in {artifacts_path}: \"\n f\"{', '.join(available_models) if available_models else 'none'}\\n\\n\"\n f\"To fix this issue:\\n\"\n f\" 1. Download the model: docling-tools models download-hf-repo {self.vlm_options.repo_id}\\n\"\n f\" 2. Or remove --artifacts-path to enable auto-download\\n\"\n f\" 3. Or use a different model that exists in your artifacts_path\"\n )\n\n # --------- Strict split & validation of extra_generation_config ---------\n extra_cfg = self.vlm_options.extra_generation_config\n\n load_cfg = {k: v for k, v in extra_cfg.items() if k in self._VLLM_ENGINE_KEYS}\n gen_cfg = {k: v for k, v in extra_cfg.items() if k in self._VLLM_SAMPLING_KEYS}\n\n unknown = sorted(\n k","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/vlm_pipeline_models/vllm_model.py#L126-L162","documentation":"Thrown by the vLLM-backed VLM pipeline model when artifacts_path is set (forcing offline mode) but the expected Hugging Face repo cache folder for vlm_options.repo_id is not present under it. The code first tries snapshot_download, then checks artifacts_path / repo_cache_folder; when neither exists it raises FileNotFoundError listing the models that ARE available. It exists to give an actionable offline-mode failure instead of a confusing later crash inside vLLM.","triggerScenarios":"Instantiating the vLLM VLM model with VlmPipelineOptions/VlmOptions where repo_id points to a model (e.g. SmolDocling-256M-preview) and artifacts_path is set to a directory that lacks models----. Happens with `docling --artifacts-path ...` or PipelineOptions(artifacts_path=...) when the model was never downloaded into that cache, or the cache was copied without the models--* layout.","commonSituations":"Air-gapped / offline deployments using --artifacts-path; CI caches that only include layout/table models but not the VLM repo; typos in repo_id; switching vlm_options.repo_id without re-downloading; artifacts_path pointed at a flat folder of weights instead of an HF-style cache.","solutions":["Prefetch the model into the same cache: docling-tools models download-hf-repo (with artifacts_path pointed at the same cache), or hf download --cache-dir ","Remove artifacts_path from your pipeline options / CLI flags so the model auto-downloads from the HF hub","Point artifacts_path at the directory that actually contains models---- for your repo_id (verify with ls /models--*)","Switch vlm_options.repo_id to one of the models listed in the error message's 'Available models' section"],"exampleFix":"# before\nopts = VlmPipelineOptions(artifacts_path=Path('/opt/models')) # missing VLM repo\n\n# after\n# shell: docling-tools models download-hf-repo ds4sd/SmolDocling-256M-preview\nopts = VlmPipelineOptions(artifacts_path=Path('/opt/models'))","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef vlm_model_available(artifacts_path: Path, repo_id: str) -> bool:\n org, name = repo_id.split('/')\n return (artifacts_path / f'models--{org}--{name}').is_dir()","typeGuard":null,"tryCatchPattern":"try:\n model = VlmModel(opts)\nexcept FileNotFoundError as e:\n if 'not found in artifacts_path' in str(e):\n raise SystemExit(f'Prefetch model: docling-tools models download-hf-repo {opts.vlm_options.repo_id}') from e\n raise","preventionTips":["Pre-download all VLM repos into the shared artifacts cache in your Docker/CI image build step","Assert the models---- directory exists before constructing the pipeline in offline mode","Keep one artifacts_path per environment and validate its contents in a startup health check"],"tags":["vlm","vllm","offline","model-download","artifacts-path"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}