docling-project/docling · error · RuntimeError

The value of {self.artifacts_path=} is not valid. When defin

Error message

The value of {self.artifacts_path=} is not valid. When defined, it must point to a folder containing all models required by the pipeline.

What it means

BaseExtractionPipeline.__init__ resolves artifacts_path from pipeline_options.artifacts_path or the global settings.artifacts_path, expands ~, and requires it to be an existing directory — extraction pipelines (e.g. ExtractionVlmPipeline) need all model artifacts under one root. A nonexistent path (file, typo, missing dir) raises RuntimeError at pipeline construction.

Source

Thrown at docling/pipeline/base_extraction_pipeline.py:31

from docling.datamodel.extraction import ExtractionResult, ExtractionTemplateType
from docling.datamodel.pipeline_options import BaseOptions, PipelineOptions
from docling.datamodel.settings import settings

_log = logging.getLogger(__name__)


class BaseExtractionPipeline(ABC):
    def __init__(self, pipeline_options: PipelineOptions):
        self.pipeline_options = pipeline_options

        self.artifacts_path: Optional[Path] = None
        if pipeline_options.artifacts_path is not None:
            self.artifacts_path = Path(pipeline_options.artifacts_path).expanduser()
        elif settings.artifacts_path is not None:
            self.artifacts_path = Path(settings.artifacts_path).expanduser()

        if self.artifacts_path is not None and not self.artifacts_path.is_dir():
            raise RuntimeError(
                f"The value of {self.artifacts_path=} is not valid. "
                "When defined, it must point to a folder containing all models required by the pipeline."
            )

    def execute(
        self,
        in_doc: InputDocument,
        raises_on_error: bool,
        template: Optional[ExtractionTemplateType] = None,
    ) -> ExtractionResult:
        ext_res = ExtractionResult(input=in_doc)

        try:
            ext_res = self._extract_data(ext_res, template)
            ext_res.status = self._determine_status(ext_res)
        except Exception as e:
            ext_res.status = ConversionStatus.FAILURE
            error_item = ErrorItem(

View on GitHub (pinned to 61d76f1ff3)

Solutions

Create the directory and populate it with the required models, then point artifacts_path at it
Fix the path (expanduser/resolve typos, mount the volume) — verify with Path(p).expanduser().is_dir()
Unset artifacts_path entirely to let models auto-download to the user cache

Example fix

# before
opts.artifacts_path = Path('~/docling-models')  # dir does not exist

# after
# mkdir -p ~/docling-models  (and populate with model artifacts)
opts.artifacts_path = Path('~/docling-models').expanduser()

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

if pipeline_options.artifacts_path is not None:
    p = Path(pipeline_options.artifacts_path).expanduser()
    if not p.is_dir():
        raise ValueError(f'artifacts_path {p} is not an existing directory')

Prevention

Expand and validate the path in your own config loader before handing it to pipeline options
Fail fast on missing model directories during deployment health checks, not at first conversion

When it happens

Trigger: Constructing an extraction pipeline with ExtractionPipelineOptions(artifacts_path=...) pointing at a missing directory, or having DOCLING_ARTIFACTS_PATH (settings) set to a bad path. Note file paths are rejected too: is_dir() must pass.

Common situations: Typos in the path; pointing at a tarball/symlink-to-nowhere instead of the extracted folder; container volumes not mounted where the option expects; a stale settings value left in the environment from another project.

Related errors

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