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

HuggingFaceTransformersVlmModel resolves the local model directory as artifacts_path/<repo_id with '/' replaced by '--'>. When artifacts_path is given, auto-download is disabled; if that folder does not exist, Docling raises FileNotFoundError listing the expected location, the models actually present, and three remediation options.

Source

Thrown at docling/models/vlm_pipeline_models/hf_transformers_model.py:122

            self.temperature = vlm_options.temperature

            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"
                )

            self.param_quantization_config: BitsAndBytesConfig | None = None
            if vlm_options.quantized:
                self.param_quantization_config = BitsAndBytesConfig(
                    load_in_8bit=vlm_options.load_in_8bit,
                    llm_int8_threshold=vlm_options.llm_int8_threshold,
                )

            model_cls: Any = AutoModel

View on GitHub (pinned to 61d76f1ff3)

Solutions

Download the model into the artifacts path: docling-tools models download-hf-repo <repo_id>
Drop --artifacts-path so Docling auto-downloads from the HF hub
Verify the folder name matches repo_id.replace('/', '--') (e.g. 'rednote-hilab--dots.ocr') or switch repo_id to one of the models listed as available

Example fix

# before
docling --artifacts-path /models -vsm rednote-hilab/dots.mocr file.pdf  # FileNotFoundError
# after
# docling-tools models download-hf-repo rednote-hilab/dots.mocr
docling --artifacts-path /models -vsm rednote-hilab/dots.mocr file.pdf

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():
    available = [p.name for p in artifacts_path.iterdir() if p.is_dir()]
    raise FileNotFoundError(f'{expected} missing; have: {available}')

Try / catch

try:
    model = HuggingFaceTransformersVlmModel(artifacts_path=artifacts_path, ...)
except FileNotFoundError as e:
    if 'not found in artifacts_path' in str(e):
        model = HuggingFaceTransformersVlmModel(artifacts_path=None, ...)  # auto-download
    else:
        raise

Prevention

Name local model dirs exactly as repo_id with '/' replaced by '--'
Add a preflight check listing artifacts_path contents before conversion
Automate provisioning with docling-tools models download-hf-repo in your setup script

When it happens

Trigger: Running with --artifacts-path /models for repo_id 'rednote-hilab/dots.mocr' when /models/rednote-hilab--dots.mocr does not exist, or artifacts_path points at an empty/wrong directory.

Common situations: CLI users passing --artifacts-path to avoid network access but the model was never fetched; repo_id typos; models directory not mounted into Docker; the '--' flattening convention unknown so the folder is named differently.

Related errors

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