docling-project/docling · error · RuntimeError

{p} does not exist or is not a directory containing the requ

Error message

{p} does not exist or is not a directory containing the required models

What it means

RuntimeError from ThreadedLayoutVlmPipeline._resolve_artifacts_path: an artifacts directory was configured (via pipeline_options.artifacts_path or settings.artifacts_path) but it does not exist or is not a directory. The pipeline needs that directory to hold downloaded model artifacts (layout/VLM models).

Source

Thrown at docling/experimental/pipeline/threaded_layout_vlm_pipeline.py:223

                    vlm_options=vlm_options,
                )
            else:
                raise ValueError(
                    f"Unsupported VLM inference framework: {vlm_options.inference_framework}"
                )
        else:
            raise ValueError(f"Unsupported VLM options type: {type(base_vlm_options)}")

    def _resolve_artifacts_path(self) -> Optional[Path]:
        """Resolve artifacts path from options or settings."""
        if self.pipeline_options.artifacts_path:
            p = Path(self.pipeline_options.artifacts_path).expanduser()
        elif settings.artifacts_path:
            p = Path(settings.artifacts_path).expanduser()
        else:
            return None
        if not p.is_dir():
            raise RuntimeError(
                f"{p} does not exist or is not a directory containing the required models"
            )
        return p

    def _create_run_ctx(self) -> RunContext:
        """Create pipeline stages and wire them together."""
        opts = self.pipeline_options

        # Layout stage
        layout_stage = ThreadedPipelineStage(
            name="layout",
            model=self.layout_model,
            batch_size=opts.layout_batch_size,
            batch_timeout=opts.batch_timeout_seconds,
            queue_max_size=opts.queue_max_size,
        )

        # Layout post-processing stage

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Point artifacts_path to an existing directory containing the required models, or unset it to let Docling manage the default download location.
2. If models are missing, pre-download/copy them into the directory (e.g. via the docling-tools artifacts flow) and re-run.
3. Check settings.artifacts_path in global settings is not accidentally overriding the pipeline-level option with a stale path.

Example fix

# before
opts = ThreadedLayoutVlmPipelineOptions(artifacts_path='/opt/models')  # missing dir

# after
from pathlib import Path
p = Path('/opt/models')
assert p.is_dir(), f'create and populate {p} first'
opts = ThreadedLayoutVlmPipelineOptions(artifacts_path=p)

from pathlib import Path
p = Path(opts.artifacts_path) if opts.artifacts_path else settings.artifacts_path
if p is not None and not Path(p).is_dir():
    raise SystemExit(f'artifacts dir {p} missing; create/download models first')

try:
    pipeline = ThreadedLayoutVlmPipeline(opts)
except RuntimeError as e:
    if 'does not exist or is not a directory' in str(e):
        raise SystemExit('fix artifacts_path or unset it to use the default download location')

When it happens

Trigger: Setting artifacts_path to a wrong/stale path, or setting the global docling settings.artifacts_path to a directory that was deleted or never created, then initializing/running the threaded pipeline.

Common situations: Docker images where the artifacts volume is not mounted at the expected path; CI caching that pruned the models dir; moving a project between machines and the absolute artifacts path no longer resolves.

Related errors

• Model '{repo_id}' not found in artifacts_path. Expected loca
• Unsupported VLM inference framework: {vlm_options.inference_
• Unknown prompt style: {prompt_style}. Valid values are {', '
• Connections to remote services is only allowed when set expl
• API runtime requires a URL

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