{"record":{"id":"f028dd167a2c1de9","repo":"docling-project/docling","slug":"local-file-access-requires-base-path-for-directory","errorCode":null,"errorMessage":"Local file access requires base_path for directory confinement: '{src_loc}'","messagePattern":"Local file access requires base_path for directory confinement: '(.+?)'","errorType":"exception","errorClass":"OperationNotAllowed","httpStatus":null,"severity":"warning","filePath":"docling/backend/utils/image_resource_loader.py","lineNumber":267,"sourceCode":"            encoded_data = re.sub(r\"^data:image/.+;base64,\", \"\", src_loc)\n            decoded_data = base64.b64decode(encoded_data)\n\n            if len(decoded_data) > self.max_image_data_base64_bytes:\n                raise ValueError(\n                    f\"Decoded image exceeds size limit of {self.max_image_data_base64_bytes} bytes.\"\n                )\n\n            return decoded_data\n\n        if not self.enable_local_fetch:\n            raise OperationNotAllowed(\n                \"Fetching local resources is only allowed when set explicitly. \"\n                \"Set options.enable_local_fetch=True.\"\n            )\n\n        # Require base_path for directory confinement (validation done in resolve_relative_path)\n        if not base_path:\n            raise OperationNotAllowed(\n                f\"Local file access requires base_path for directory confinement: '{src_loc}'\"\n            )\n\n        if os.path.isfile(src_loc) and os.access(src_loc, os.R_OK):\n            with open(src_loc, \"rb\") as f:\n                return f.read()\n        else:\n            raise ValueError(\"File does not exist or it is not readable.\")\n","sourceCodeStart":249,"sourceCodeEnd":276,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/utils/image_resource_loader.py#L249-L276","documentation":"Local fetching was enabled (enable_local_fetch=True), but the caller did not supply base_path, which docling requires for directory confinement of local file access. Without a base_path, any absolute path in the document could be read, so the loader refuses. Raised as OperationNotAllowed.","triggerScenarios":"Calling ImageResourceLoader.load_image_data / load_image_ref with base_path=None (or empty) for a local path when enable_local_fetch=True; typically because the backend was not given the source document's directory.","commonSituations":"Converting an HTML/Markdown stream (BytesIO) with no file path, so no base directory exists to confine against; passing document content via string without telling docling where related assets live; programmatic pipelines that only handle buffers.","solutions":["Provide the document's directory as base_path so relative image paths resolve and are confined to it.","If converting from a stream, first write to a real file (or use a temp dir) so a base_path exists.","Co-locate images under that directory and reference them relatively in the source document.","If local images are not needed, leave enable_local_fetch unset and accept skipped images."],"exampleFix":"# before\nresult = converter.convert(BytesIO(html_bytes))  # no base dir -> local fetch refused\n\n# after\n# convert from a real file so the backend derives base_path from its parent dir\nresult = converter.convert(Path(\"/data/report/index.html\"))","handlingStrategy":"validation","validationCode":"def can_fetch_local(enable_local_fetch: bool, base_path: str | None) -> bool:\n    return (not enable_local_fetch) or bool(base_path)  # False -> error [84] imminent when fetching","typeGuard":null,"tryCatchPattern":"try:\n    data = loader.load_image_data(src, base_path)\nexcept OperationNotAllowed as e:\n    if \"base_path\" in str(e):\n        logger.warning(\"no base_path supplied; local image %s skipped\", src)","preventionTips":["Convert from real files (Path) so the backend derives base_path from the parent directory.","For stream-based input, materialize the document to a temp dir first.","Always pair enable_local_fetch=True with a concrete base directory."],"tags":["security","images","local-files","path-confinement","configuration"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}