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

Identical guard in BasePipeline (the base for standard conversion pipelines like StandardPdfPipeline): artifacts_path, taken from pipeline_options.artifacts_path or the docling settings.artifacts_path, must be an existing directory because all pipeline models are loaded offline from it. RuntimeError is raised in __init__, i.e. at DocumentConverter construction/pipeline instantiation time.

Source

Thrown at docling/pipeline/base_pipeline.py:60

_log = logging.getLogger(__name__)


class BasePipeline(ABC):
    def __init__(self, pipeline_options: PipelineOptions):
        self.pipeline_options = pipeline_options
        self.keep_images = False
        self.build_pipe: List[Callable] = []
        self.enrichment_pipe: List[GenericEnrichmentModel[Any]] = []

        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) -> ConversionResult:
        conv_res = ConversionResult(input=in_doc)

        _log.info(f"Processing document {in_doc.file.name}")
        try:
            with TimeRecorder(
                conv_res, "pipeline_total", scope=ProfilingScope.DOCUMENT
            ):
                # These steps are building and assembling the structure of the
                # output DoclingDocument.
                conv_res = self._build_document(conv_res)
                conv_res = self._assemble_document(conv_res)
                # From this stage, all operations should rely only on conv_res.output
                conv_res = self._enrich_document(conv_res)

View on GitHub (pinned to 61d76f1ff3)

Solutions

Point artifacts_path at the real directory containing the downloaded models and verify it exists first
If the env var is stale, unset DOCLING_ARTIFACTS_PATH / clear settings.artifacts_path
Omit artifacts_path to use default auto-download into the user cache

Example fix

# before
opts = PdfPipelineOptions(artifacts_path=Path('/opt/docling-models'))  # not mounted

# after
models = Path('/opt/docling-models')
assert models.is_dir(), f'mount models volume at {models}'
opts = PdfPipelineOptions(artifacts_path=models)

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

artifacts = Path(opts.artifacts_path or settings.artifacts_path or '').expanduser()
if str(artifacts) != '.' and not artifacts.is_dir():
    raise ValueError(f'artifacts_path {artifacts} is not an existing directory')

Prevention

Validate artifacts_path early in app startup with Path(...).expanduser().is_dir()
In containers, assert the models volume is mounted before constructing DocumentConverter
Watch for stale DOCLING_ARTIFACTS_PATH env vars overriding your intended path

When it happens

Trigger: PdfPipelineOptions(artifacts_path=Path('/missing/dir')), `docling --artifacts-path /missing/dir`, or settings.artifacts_path (env var) pointing somewhere that is not a directory (including pointing at a file).

Common situations: CI or Docker runs where the models volume is mounted at a different path than the option specifies; relative paths resolved against an unexpected cwd; leftover DOCLING_ARTIFACTS_PATH env var; path with unexpanded '~' passed as a raw string in code that bypasses expanduser on the caller side.

Related errors

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