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

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.

Source

Thrown at docling/models/vlm_pipeline_models/vllm_model.py:144

        _log.debug(f"Available device for VLM: {self.device}")

        # Resolve artifacts path / cache folder
        repo_cache_folder = vlm_options.repo_id.replace("/", "--")
        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"
            )

        # --------- Strict split & validation of extra_generation_config ---------
        extra_cfg = self.vlm_options.extra_generation_config

        load_cfg = {k: v for k, v in extra_cfg.items() if k in self._VLLM_ENGINE_KEYS}
        gen_cfg = {k: v for k, v in extra_cfg.items() if k in self._VLLM_SAMPLING_KEYS}

        unknown = sorted(
            k

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Prefetch the model into the same cache: docling-tools models download-hf-repo <repo_id> (with artifacts_path pointed at the same cache), or hf download <repo_id> --cache-dir <artifacts_path>
2. Remove artifacts_path from your pipeline options / CLI flags so the model auto-downloads from the HF hub
3. Point artifacts_path at the directory that actually contains models--<org>--<name> for your repo_id (verify with ls <artifacts_path>/models--*)
4. Switch vlm_options.repo_id to one of the models listed in the error message's 'Available models' section

Example fix

# before
opts = VlmPipelineOptions(artifacts_path=Path('/opt/models'))  # missing VLM repo

# after
# shell: docling-tools models download-hf-repo ds4sd/SmolDocling-256M-preview
opts = VlmPipelineOptions(artifacts_path=Path('/opt/models'))

from pathlib import Path

def vlm_model_available(artifacts_path: Path, repo_id: str) -> bool:
    org, name = repo_id.split('/')
    return (artifacts_path / f'models--{org}--{name}').is_dir()

try:
    model = VlmModel(opts)
except FileNotFoundError as e:
    if 'not found in artifacts_path' in str(e):
        raise SystemExit(f'Prefetch model: docling-tools models download-hf-repo {opts.vlm_options.repo_id}') from e
    raise

When it happens

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

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

Related errors

• Model '{repo_id}' not found in artifacts_path. Expected loca
• Model '{repo_id}' not found in artifacts_path. Expected loca
• Expected VllmVlmEngineOptions, got {type(options)}
• {repo_id} is supported by the Transformers engine only with
• vLLM is not installed. Please install it via `pip install vl

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