{"record":{"id":"cf59c5ec5dc8adfc","repo":"docling-project/docling","slug":"invalid-base-path-format-base-path","errorCode":null,"errorMessage":"Invalid base_path format: '{base_path}'","messagePattern":"Invalid base_path format: '(.+?)'","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/backend/utils/image_resource_loader.py","lineNumber":156,"sourceCode":"            elif not loc.startswith((\"http://\", \"https://\", \"data:\", \"#\")):\n                if ImageResourceLoader.is_remote_url(base_path):\n                    abs_loc = urljoin(base_path, loc)\n                elif ImageResourceLoader.is_local_path(base_path):\n                    if ImageResourceLoader.is_absolute_path(loc):\n                        raise ValueError(\n                            f\"Absolute paths are not allowed with local base_path: '{loc}'\"\n                        )\n\n                    base_dir = Path(base_path).parent.resolve()\n                    resolved_path = (base_dir / loc).resolve()\n\n                    if not resolved_path.is_relative_to(base_dir):\n                        raise ValueError(\n                            f\"Path traversal blocked: '{loc}' resolves outside base directory\"\n                        )\n                    abs_loc = str(resolved_path)\n                else:\n                    raise ValueError(f\"Invalid base_path format: '{base_path}'\")\n\n        _log.debug(f\"Resolved location {loc} to {abs_loc}\")\n        return abs_loc\n\n    def create_image_ref(\n        self, src_url: str, base_path: Optional[str]\n    ) -> Optional[ImageRef]:\n        try:\n            img_data = self.load_image_data(src_url, base_path)\n            if img_data:\n                img = Image.open(BytesIO(img_data))\n                return ImageRef.from_pil(img, dpi=int(img.info.get(\"dpi\", (72,))[0]))\n        except (\n            requests.HTTPError,\n            ValidationError,\n            UnidentifiedImageError,\n            OperationNotAllowed,\n            TypeError,","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/utils/image_resource_loader.py#L138-L174","documentation":"ValueError raised in resolve_relative_path when the location is relative but base_path is neither a remote URL (is_remote_url) nor a local path (is_local_path). The resolver cannot decide how to join the reference, so it refuses rather than guessing.","triggerScenarios":"Passing a base_path like a bare fragment, malformed string, or unsupported scheme (e.g. 'ftp://x/', ':::') together with a relative image location; the two is_* checks both fail and the else branch raises.","commonSituations":"Programmatic callers constructing base_path from unvalidated user input or config values; documents whose retrieval URL was mangled upstream; passing a Path object where a string URL was expected in custom code.","solutions":["Pass a well-formed base: an http(s) URL or a local filesystem path string ending in the document filename.","Validate base_path before conversion (must start with http://, https://, file:/, or be an existing local path).","Omit base_path (None) only when all image refs are absolute."],"exampleFix":"# before\nloader.resolve_relative_path('img.png', 'example.com/docs/page')  # ValueError\n\n# after\nloader.resolve_relative_path('img.png', 'https://example.com/docs/page')","handlingStrategy":"validation","validationCode":"def valid_base(bp: str | None) -> bool:\n    if bp is None:\n        return True\n    return bp.startswith(('http://', 'https://', 'file:')) or Path(bp).exists()\nassert valid_base(base_path), f'bad base_path: {base_path}'","typeGuard":"from pathlib import Path\ndef is_usable_base(bp: object) -> bool:\n    return bp is None or (isinstance(bp, str) and (bp.startswith(('http://', 'https://')) or Path(bp).exists()))","tryCatchPattern":"try:\n    loc = loader.resolve_relative_path(src, base)\nexcept ValueError as e:\n    if 'Invalid base_path' in str(e):\n        loc = loader.resolve_relative_path(src, str(document_dir / 'index.html'))\n    else:\n        raise","preventionTips":["Derive base_path from the document's own URL/path, never from raw user config","Validate base_path shape before batch runs","Pass None as base only when every image ref is already absolute"],"tags":["base-path","images","validation"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}