docling-project/docling · error · FileNotFoundError

Model '{repo_id}' not found in artifacts_path. Expected loca

Error message

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

To fix this issue:
  1. Download the model: docling-tools models download-hf-repo {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

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.

Source

Thrown at docling/models/inference_engines/vlm/mlx_engine.py:132

        """
        from mlx_vlm import load
        from mlx_vlm.utils import load_config

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

            raise FileNotFoundError(
                f"Model '{repo_id}' not found in artifacts_path.\n"
                f"Expected location: {self.artifacts_path / repo_cache_folder}\n"
                f"Available models in {self.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 {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)

        _log.info(f"Loaded MLX model {repo_id} (revision: {revision})")

    def predict_batch(self, input_batch: List[VlmEngineInput]) -> List[VlmEngineOutput]:
        """Run inference on a batch of inputs.

View on GitHub (pinned to 61d76f1ff3)

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

Example fix

# before
engine = MlxVlmEngine(
    options=MlxVlmEngineOptions(),
    model_config=EngineModelConfig(repo_id='ds4sd/SmolDocling-256M-preview'),
    artifacts_path=Path('/models'),  # '/models' lacks the repo folder
)

# after
# terminal: docling-tools models download-hf-repo ds4sd/SmolDocling-256M-preview --artifacts-path /models  # or omit artifacts_path:
engine = MlxVlmEngine(
    options=MlxVlmEngineOptions(),
    model_config=EngineModelConfig(repo_id='ds4sd/SmolDocling-256M-preview'),
    artifacts_path=None,  # enables auto-download
)

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def model_in_artifacts(artifacts_path: Path, repo_id: str) -> bool:
    cache_folder = repo_id.replace('/', '--')  # match the engine's repo_cache_folder layout
    if cache_folder.startswith('models--'):
        folder = cache_folder
    else:
        folder = f'models--{cache_folder}'
    return (artifacts_path / folder).exists()

# before building the engine:
assert artifacts_path is None or model_in_artifacts(Path(artifacts_path), repo_id), (
    f'{repo_id} missing from {artifacts_path}; run: docling-tools models download-hf-repo {repo_id}'
)

Try / catch

try:
    engine.initialize()
except FileNotFoundError as e:
    msg = str(e)
    if 'not found in artifacts_path' in msg:
        # either pre-download or fall back to auto-download
        engine.artifacts_path = None
        engine.initialize()
    else:
        raise

Prevention

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

When it happens

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

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

Related errors

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