docling-project/docling · error · FileNotFoundError

Model '{self.vlm_options.repo_id}' not found in artifacts_pa

Error message

Model '{self.vlm_options.repo_id}' not found in artifacts_path.
Expected location: {artifacts_path / repo_cache_folder}
Available models in {artifacts_path}: {', '.join(available_models) if available_models else 'none'}

To fix this issue:
  1. Download the model: docling-tools models download-hf-repo {self.vlm_options.repo_id}
  2. Or remove --artifacts-path to enable auto-download
  3. Or use a different model that exists in your artifacts_path

What it means

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.

Source

Thrown at docling/models/vlm_pipeline_models/mlx_model.py:83

            self.stream_generate = stream_generate

            # PARAMETERS:
            if artifacts_path is None:
                artifacts_path = self.download_models(
                    self.vlm_options.repo_id,
                    revision=self.vlm_options.revision,
                )
            elif (artifacts_path / repo_cache_folder).exists():
                artifacts_path = artifacts_path / repo_cache_folder
            else:
                # Model not found in artifacts_path - raise clear error
                available_models = []
                if artifacts_path.exists():
                    available_models = [
                        p.name for p in artifacts_path.iterdir() if p.is_dir()
                    ]

                raise FileNotFoundError(
                    f"Model '{self.vlm_options.repo_id}' not found in artifacts_path.\n"
                    f"Expected location: {artifacts_path / repo_cache_folder}\n"
                    f"Available models in {artifacts_path}: "
                    f"{', '.join(available_models) if available_models else 'none'}\n\n"
                    f"To fix this issue:\n"
                    f"  1. Download the model: docling-tools models download-hf-repo {self.vlm_options.repo_id}\n"
                    f"  2. Or remove --artifacts-path to enable auto-download\n"
                    f"  3. Or use a different model that exists in your artifacts_path"
                )

            ## Load the model
            self.vlm_model, self.processor = load(artifacts_path)
            self.config = load_config(artifacts_path)

            # Validate custom stopping criteria - MLX doesn't support HF StoppingCriteria
            if self.vlm_options.custom_stopping_criteria:
                for criteria in self.vlm_options.custom_stopping_criteria:
                    if isinstance(criteria, StoppingCriteria):

View on GitHub (pinned to 61d76f1ff3)

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

Example fix

# before
model = MlxVlmModel(enabled=True, artifacts_path=Path('/models'), ...)
# FileNotFoundError
# after
# docling-tools models download-hf-repo rednote-hilab/dots.ocr
model = MlxVlmModel(enabled=True, artifacts_path=Path('/models'), ...)

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

expected = artifacts_path / vlm_options.repo_id.replace('/', '--')
if artifacts_path is not None and not expected.is_dir():
    raise FileNotFoundError(f'missing {expected}; run docling-tools models download-hf-repo {vlm_options.repo_id}')

Try / catch

try:
    model = MlxVlmModel(artifacts_path=artifacts_path, ...)
except FileNotFoundError:
    model = MlxVlmModel(artifacts_path=None, ...)  # allow auto-download

Prevention

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

When it happens

Trigger: 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.

Common situations: 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 '/'.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/94be1701c9b188ce. Report an issue: GitHub.