docling-project/docling · warning · OperationNotAllowed

Fetching local resources is only allowed when set explicitly

Error message

Fetching local resources is only allowed when set explicitly. Set options.enable_local_fetch=True.

What it means

The image resource loader was asked to fetch a local filesystem path (from an <img src> or Markdown image reference), but enable_local_fetch defaults to False, so docling raises OperationNotAllowed. This is an SSRF/local-file-read guard: documents come from untrusted parties, so reading arbitrary local paths referenced inside them is opt-in.

Source

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

                    total_size += len(chunk)
                    if total_size > max_size:
                        raise ValueError("Downloaded data exceeds size limit")
                    chunks.append(chunk)

            return b"".join(chunks)
        elif src_loc.startswith("data:"):
            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

Opt in explicitly: set options.enable_local_fetch=True on the pipeline options for that conversion.
Also pass a base_path (the directory containing the document) so relative src values resolve and stay confined.
If you don't need local images, ignore it — create_image_ref catches OperationNotAllowed, warns, and continues without the image.
For remote-hosted images instead, enable enable_remote_fetch=True and fix the src URLs.

Example fix

# before
html_opts = HtmlPipelineOptions()
result = converter.convert(html_path)

# after
html_opts = HtmlPipelineOptions()
html_opts.enable_local_fetch = True
converter = DocumentConverter(
    format_options={InputFormat.HTML: HtmlFormatOptions(pipeline_options=html_opts)}
)
result = converter.convert(html_path)

Defensive patterns

Strategy: validation

Validate before calling

from urllib.parse import urlparse

def will_local_fetch_be_attempted(src: str, enable_local_fetch: bool) -> bool:
    p = urlparse(src)
    is_local = not p.netloc and (not p.scheme or (len(p.scheme) == 1 and p.scheme.isalpha()))
    return is_local and not enable_local_fetch  # True -> error [83] imminent

Try / catch

try:
    img = loader.load_image_ref(src, base_path)
except OperationNotAllowed as e:
    logger.info("local image skipped (enable_local_fetch=False): %s", src)

Prevention

Default conversions of local HTML/Markdown with images: always set enable_local_fetch=True plus a base_path.
Never blanket-enable local fetch for untrusted documents; confine with base_path.
Know that via create_image_ref this is a warning, not a crash.

When it happens

Trigger: Converting HTML/Markdown with relative or absolute local image paths while pipeline options leave enable_local_fetch=False (the default). The loader's resolve_relative_path produced a local path and load_image_data reached the local branch.

Common situations: First-time users converting a local .html with sibling images and expecting them to be embedded; batch pipelines processing downloaded HTML; migrating from a version/looser config that auto-fetched.

Related errors

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