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: {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 {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 resolving a VLM model location, if artifacts_path is set but the expected repo subfolder does not exist under it, Docling raises FileNotFoundError listing the expected path, the models actually available, and three remediation steps. This makes offline/air-gapped misconfiguration explicit instead of attempting a network download that was implicitly forbidden by supplying artifacts_path.

Source

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

        FileNotFoundError: If artifacts_path is provided but model not found
    """
    repo_cache_folder = repo_id.replace("/", "--")

    artifacts_path = artifacts_path if artifacts_path is None else Path(artifacts_path)

    if artifacts_path is None:
        # No cache path provided - download
        return download_fn(repo_id, revision)
    elif (artifacts_path / repo_cache_folder).exists():
        # Cache path with repo-specific subfolder exists
        return 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 '{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 {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"
        )


def format_prompt_for_vlm(
    prompt: str,
    processor: Any,
    prompt_style: TransformersPromptStyle,
    repo_id: Optional[str] = None,
) -> Optional[str]:
    """Format a prompt according to the specified style.

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Download the model into the artifacts path exactly as the message instructs: docling-tools models download-hf-repo <repo_id> (targeting that artifacts directory).
2. Verify the expected subfolder name shown in the error exists under your artifacts_path (watch repo-id slashes/casing) — copy/symlink the model folder to that name.
3. If network access is allowed, simply omit artifacts_path so Docling auto-downloads from HF.

Example fix

# before
docling convert doc.pdf --artifacts-path /models --vlm-engine ...  # /models lacks models--org--name

# after
# 1) download into the artifacts dir:
docling-tools models download-hf-repo org/name --download-dir /models
# 2) or drop the flag to allow auto-download:
docling convert doc.pdf --vlm-engine ...

from pathlib import Path
repo_folder = repo_id.replace('/', '--')
if artifacts_path is not None and not (artifacts_path / repo_folder).exists():
    raise FileNotFoundError(f"{repo_id} missing under {artifacts_path}; run docling-tools models download-hf-repo {repo_id}")

try:
    converter = DocumentConverter(format_options={InputFormat.PDF: PdfFormatOptions(pipeline_options=opts)})
except FileNotFoundError as e:
    log.error("VLM model not in artifacts_path: %s", e)
    raise

When it happens

Trigger: Passing artifacts_path (CLI --artifacts-path or PipelineOptions) pointing at a directory that does not contain the model's repo-id subfolder — e.g. the folder holds other models, or the target model was never downloaded into it.

Common situations: Offline servers where the model was downloaded to a different path than the one passed; typos in artifacts_path; models downloaded under a different repo-id casing; sharing an artifacts dir between docling versions with different default VLM models.

Related errors

• Model '{repo_id}' not found in artifacts_path. Expected loca
• {p} does not exist or is not a directory containing the requ
• ONNX model file '{model_filename}' not found: {model_path}
• Unsupported VLM inference framework: {vlm_options.inference_
• Image processor config not found: {preprocessor_config}

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