{"record":{"id":"94be1701c9b188ce","repo":"docling-project/docling","slug":"model-self-vlm-options-repo-id-not-found-in-ar-94be17","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/mlx_model.py","lineNumber":83,"sourceCode":"            self.stream_generate = stream_generate\n\n            # PARAMETERS:\n            if artifacts_path is None:\n                artifacts_path = self.download_models(\n                    self.vlm_options.repo_id,\n                    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            ## Load the model\n            self.vlm_model, self.processor = load(artifacts_path)\n            self.config = load_config(artifacts_path)\n\n            # Validate custom stopping criteria - MLX doesn't support HF StoppingCriteria\n            if self.vlm_options.custom_stopping_criteria:\n                for criteria in self.vlm_options.custom_stopping_criteria:\n                    if isinstance(criteria, StoppingCriteria):","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/vlm_pipeline_models/mlx_model.py#L65-L101","documentation":"MlxVlmModel uses the same offline resolution scheme as the Transformers model: with artifacts_path set, it expects artifacts_path/<repo_id with '/' replaced by '--'> to exist and raises FileNotFoundError (with available models and fix steps) when it does not. Auto-download only happens when artifacts_path is None.","triggerScenarios":"Initializing MlxVlmModel with artifacts_path set while artifacts_path/<repo_id with '/'->'--'> does not exist, e.g. /models/rednote-hilab--dots.ocr missing from /models.","commonSituations":"Sharing an artifacts dir between engines but only downloading weights for one; running air-gapped conversions before pre-fetching MLX weights; naming the model folder with the raw repo_id containing '/'.","solutions":["Pre-download: docling-tools models download-hf-repo <repo_id> into your artifacts path","Omit --artifacts-path/artifacts_path to let Docling download automatically","Check the folder name uses '--' in place of '/', or pick a repo already present in the listed available models"],"exampleFix":"# before\nmodel = MlxVlmModel(enabled=True, artifacts_path=Path('/models'), ...)\n# FileNotFoundError\n# after\n# docling-tools models download-hf-repo rednote-hilab/dots.ocr\nmodel = MlxVlmModel(enabled=True, artifacts_path=Path('/models'), ...)","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\nexpected = artifacts_path / vlm_options.repo_id.replace('/', '--')\nif artifacts_path is not None and not expected.is_dir():\n    raise FileNotFoundError(f'missing {expected}; run docling-tools models download-hf-repo {vlm_options.repo_id}')","typeGuard":null,"tryCatchPattern":"try:\n    model = MlxVlmModel(artifacts_path=artifacts_path, ...)\nexcept FileNotFoundError:\n    model = MlxVlmModel(artifacts_path=None, ...)  # allow auto-download","preventionTips":["Use the '--' folder naming convention when staging local models","Provision models with docling-tools in your image build, not at runtime","Print artifacts_path contents on startup in offline deployments"],"tags":["model-download","artifacts-path","mlx","file-not-found"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}