docling-project/docling · warning · OperationNotAllowed

Local file access requires base_path for directory confineme

Error message

Local file access requires base_path for directory confinement: '{src_loc}'

What it means

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.

Source

Thrown at docling/backend/utils/image_resource_loader.py:267

            encoded_data = re.sub(r"^data:image/.+;base64,", "", src_loc)
            decoded_data = base64.b64decode(encoded_data)

            if len(decoded_data) > self.max_image_data_base64_bytes:
                raise ValueError(
                    f"Decoded image exceeds size limit of {self.max_image_data_base64_bytes} bytes."
                )

            return decoded_data

        if not self.enable_local_fetch:
            raise OperationNotAllowed(
                "Fetching local resources is only allowed when set explicitly. "
                "Set options.enable_local_fetch=True."
            )

        # Require base_path for directory confinement (validation done in resolve_relative_path)
        if not base_path:
            raise OperationNotAllowed(
                f"Local file access requires base_path for directory confinement: '{src_loc}'"
            )

        if os.path.isfile(src_loc) and os.access(src_loc, os.R_OK):
            with open(src_loc, "rb") as f:
                return f.read()
        else:
            raise ValueError("File does not exist or it is not readable.")

View on GitHub (pinned to 61d76f1ff3)

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.

Example fix

# before
result = converter.convert(BytesIO(html_bytes))  # no base dir -> local fetch refused

# after
# convert from a real file so the backend derives base_path from its parent dir
result = converter.convert(Path("/data/report/index.html"))

Defensive patterns

Strategy: validation

Validate before calling

def can_fetch_local(enable_local_fetch: bool, base_path: str | None) -> bool:
    return (not enable_local_fetch) or bool(base_path)  # False -> error [84] imminent when fetching

Try / catch

try:
    data = loader.load_image_data(src, base_path)
except OperationNotAllowed as e:
    if "base_path" in str(e):
        logger.warning("no base_path supplied; local image %s skipped", src)

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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