{"record":{"id":"9dc65694895bc8a7","repo":"docling-project/docling","slug":"the-value-of-self-artifacts-path-is-not-valid-9dc656","errorCode":null,"errorMessage":"The value of {self.artifacts_path=} is not valid. When defined, it must point to a folder containing all models required by the pipeline.","messagePattern":"The value of (.+?) is not valid\\. When defined, it must point to a folder containing all models required by the pipeline\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/pipeline/base_pipeline.py","lineNumber":60,"sourceCode":"\n_log = logging.getLogger(__name__)\n\n\nclass BasePipeline(ABC):\n    def __init__(self, pipeline_options: PipelineOptions):\n        self.pipeline_options = pipeline_options\n        self.keep_images = False\n        self.build_pipe: List[Callable] = []\n        self.enrichment_pipe: List[GenericEnrichmentModel[Any]] = []\n\n        self.artifacts_path: Optional[Path] = None\n        if pipeline_options.artifacts_path is not None:\n            self.artifacts_path = Path(pipeline_options.artifacts_path).expanduser()\n        elif settings.artifacts_path is not None:\n            self.artifacts_path = Path(settings.artifacts_path).expanduser()\n\n        if self.artifacts_path is not None and not self.artifacts_path.is_dir():\n            raise RuntimeError(\n                f\"The value of {self.artifacts_path=} is not valid. \"\n                \"When defined, it must point to a folder containing all models required by the pipeline.\"\n            )\n\n    def execute(self, in_doc: InputDocument, raises_on_error: bool) -> ConversionResult:\n        conv_res = ConversionResult(input=in_doc)\n\n        _log.info(f\"Processing document {in_doc.file.name}\")\n        try:\n            with TimeRecorder(\n                conv_res, \"pipeline_total\", scope=ProfilingScope.DOCUMENT\n            ):\n                # These steps are building and assembling the structure of the\n                # output DoclingDocument.\n                conv_res = self._build_document(conv_res)\n                conv_res = self._assemble_document(conv_res)\n                # From this stage, all operations should rely only on conv_res.output\n                conv_res = self._enrich_document(conv_res)","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/pipeline/base_pipeline.py#L42-L78","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"# before\nopts = PdfPipelineOptions(artifacts_path=Path('/opt/docling-models'))  # not mounted\n\n# after\nmodels = Path('/opt/docling-models')\nassert models.is_dir(), f'mount models volume at {models}'\nopts = PdfPipelineOptions(artifacts_path=models)","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\nartifacts = Path(opts.artifacts_path or settings.artifacts_path or '').expanduser()\nif str(artifacts) != '.' and not artifacts.is_dir():\n    raise ValueError(f'artifacts_path {artifacts} is not an existing directory')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["artifacts-path","configuration","pipeline-setup","filesystem"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}