{"record":{"id":"394880d9bf335750","repo":"docling-project/docling","slug":"the-value-of-self-artifacts-path-is-not-valid","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_extraction_pipeline.py","lineNumber":31,"sourceCode":"from docling.datamodel.extraction import ExtractionResult, ExtractionTemplateType\nfrom docling.datamodel.pipeline_options import BaseOptions, PipelineOptions\nfrom docling.datamodel.settings import settings\n\n_log = logging.getLogger(__name__)\n\n\nclass BaseExtractionPipeline(ABC):\n    def __init__(self, pipeline_options: PipelineOptions):\n        self.pipeline_options = pipeline_options\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(\n        self,\n        in_doc: InputDocument,\n        raises_on_error: bool,\n        template: Optional[ExtractionTemplateType] = None,\n    ) -> ExtractionResult:\n        ext_res = ExtractionResult(input=in_doc)\n\n        try:\n            ext_res = self._extract_data(ext_res, template)\n            ext_res.status = self._determine_status(ext_res)\n        except Exception as e:\n            ext_res.status = ConversionStatus.FAILURE\n            error_item = ErrorItem(","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/pipeline/base_extraction_pipeline.py#L13-L49","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nopts.artifacts_path = Path('~/docling-models')  # dir does not exist\n\n# after\n# mkdir -p ~/docling-models  (and populate with model artifacts)\nopts.artifacts_path = Path('~/docling-models').expanduser()","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\nif pipeline_options.artifacts_path is not None:\n    p = Path(pipeline_options.artifacts_path).expanduser()\n    if not p.is_dir():\n        raise ValueError(f'artifacts_path {p} is not an existing directory')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["artifacts-path","configuration","extraction-pipeline","filesystem"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}