{"record":{"id":"77b53578b1f47e38","repo":"docling-project/docling","slug":"model-repo-id-not-found-in-artifacts-path-exp-77b535","errorCode":null,"errorMessage":"Model '{repo_id}' not found in artifacts_path.\nExpected location: {self.artifacts_path / repo_cache_folder}\nAvailable models in {self.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 {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/inference_engines/vlm/mlx_engine.py","lineNumber":132,"sourceCode":"        \"\"\"\n        from mlx_vlm import load\n        from mlx_vlm.utils import load_config\n\n        # Download or locate model artifacts\n        repo_cache_folder = repo_id.replace(\"/\", \"--\")\n        if self.artifacts_path is None:\n            artifacts_path = self.download_models(repo_id, revision=revision)\n        elif (self.artifacts_path / repo_cache_folder).exists():\n            artifacts_path = self.artifacts_path / repo_cache_folder\n        else:\n            # Model not found in artifacts_path - raise clear error\n            available_models = []\n            if self.artifacts_path.exists():\n                available_models = [\n                    p.name for p in self.artifacts_path.iterdir() if p.is_dir()\n                ]\n\n            raise FileNotFoundError(\n                f\"Model '{repo_id}' not found in artifacts_path.\\n\"\n                f\"Expected location: {self.artifacts_path / repo_cache_folder}\\n\"\n                f\"Available models in {self.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 {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        # Load the model\n        self.vlm_model, self.processor = load(artifacts_path)\n        self.config = load_config(artifacts_path)\n\n        _log.info(f\"Loaded MLX model {repo_id} (revision: {revision})\")\n\n    def predict_batch(self, input_batch: List[VlmEngineInput]) -> List[VlmEngineOutput]:\n        \"\"\"Run inference on a batch of inputs.","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/vlm/mlx_engine.py#L114-L150","documentation":"When MlxVlmEngine is given an explicit artifacts_path, it expects the model under artifacts_path/<repo_cache_folder> and refuses to fall back to network download. If that directory is missing it lists what is actually in artifacts_path and raises FileNotFoundError with remediation steps, so stale or wrong artifact roots fail fast instead of downloading silently.","triggerScenarios":"Creating MlxVlmEngine with artifacts_path set (e.g. --artifacts-path on the CLI or a pipeline option) and a repo_id whose cache folder (models--<org>--<name> style) is not present under that path.","commonSituations":"Air-gapped or offline setups where artifacts_path was supposed to be pre-populated; pointing artifacts_path at the wrong directory; partial downloads interrupted before the model folder was created; repo_id typo so the folder name never matches.","solutions":["Pre-download the model into the artifacts path: docling-tools models download-hf-repo <repo_id>","Or drop artifacts_path (pass None) so the engine auto-downloads via download_models()","Check the 'Available models' list in the error and either fix the repo_id or use a model that is already there"],"exampleFix":"# before\nengine = MlxVlmEngine(\n    options=MlxVlmEngineOptions(),\n    model_config=EngineModelConfig(repo_id='ds4sd/SmolDocling-256M-preview'),\n    artifacts_path=Path('/models'),  # '/models' lacks the repo folder\n)\n\n# after\n# terminal: docling-tools models download-hf-repo ds4sd/SmolDocling-256M-preview --artifacts-path /models  # or omit artifacts_path:\nengine = MlxVlmEngine(\n    options=MlxVlmEngineOptions(),\n    model_config=EngineModelConfig(repo_id='ds4sd/SmolDocling-256M-preview'),\n    artifacts_path=None,  # enables auto-download\n)","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef model_in_artifacts(artifacts_path: Path, repo_id: str) -> bool:\n    cache_folder = repo_id.replace('/', '--')  # match the engine's repo_cache_folder layout\n    if cache_folder.startswith('models--'):\n        folder = cache_folder\n    else:\n        folder = f'models--{cache_folder}'\n    return (artifacts_path / folder).exists()\n\n# before building the engine:\nassert artifacts_path is None or model_in_artifacts(Path(artifacts_path), repo_id), (\n    f'{repo_id} missing from {artifacts_path}; run: docling-tools models download-hf-repo {repo_id}'\n)","typeGuard":null,"tryCatchPattern":"try:\n    engine.initialize()\nexcept FileNotFoundError as e:\n    msg = str(e)\n    if 'not found in artifacts_path' in msg:\n        # either pre-download or fall back to auto-download\n        engine.artifacts_path = None\n        engine.initialize()\n    else:\n        raise","preventionTips":["Pre-populate offline artifact roots with docling-tools models download-hf-repo and verify with ls before running","In CI or air-gapped runs, assert the expected model folders exist under artifacts_path as a preflight step","Prefer artifacts_path=None when network access is allowed, so missing models auto-download"],"tags":["vlm","mlx","model-download","artifacts","offline","file-not-found"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}