docling-project/docling · warning · ValueError

Decoded image exceeds size limit of {self.max_image_data_bas

Error message

Decoded image exceeds size limit of {self.max_image_data_base64_bytes} bytes.

What it means

A data: URI embedded image was base64-decoded and its decoded size exceeds max_image_data_base64_bytes (default 20 MiB, from backend options). This bounds memory blow-up from inline images in HTML/Markdown. The whole data URI is already in the source document, so decoding happened locally.

Source

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

            if content_length and int(content_length) > max_size:
                raise ValueError(f"Resource size exceeds limit: {content_length} bytes")

            chunks = []
            total_size = 0
            for chunk in response.iter_content(chunk_size=8192):
                if chunk:
                    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):

View on GitHub (pinned to 61d76f1ff3)

Solutions

  1. Raise max_image_data_base64_bytes in your pipeline/backend options if the inline images are legitimate.
  2. Pre-process the input to extract data URIs into separate image files and reference them via local paths with enable_local_fetch + base_path.
  3. Strip or downsample oversized inline images before conversion if you don't need them.

Example fix

# before
html_opts = HtmlPipelineOptions()  # default 20 MiB inline image cap

# after
html_opts = HtmlPipelineOptions()
html_opts.max_image_data_base64_bytes = 100 * 1024 * 1024
Defensive patterns

Strategy: validation

Validate before calling

import base64, re

def inline_image_within_limit(data_uri: str, max_decoded: int) -> bool:
    m = re.match(r"^data:image/.+;base64,(.*)$", data_uri, re.S)
    if not m:
        return True
    b64 = m.group(1)
    approx = len(b64) * 3 // 4
    return approx <= max_decoded

Try / catch

try:
    data = loader.load_image_data(src, base_path)
except ValueError as e:
    if "size limit" in str(e):
        logger.warning("inline image too large, skipping")
    else:
        raise

Prevention

When it happens

Trigger: Input HTML/Markdown contains <img src="data:image/...;base64,..."> whose decoded payload is larger than options.max_image_data_base64_bytes (the loader receives it from HtmlBackend/MdBackend options).

Common situations: Single-file HTML exports (e.g. 'save as complete webpage', Jupyter/Pandas exports) inlining print-resolution screenshots; a security policy lowering the default; WYSIWYG editors embedding pasted screenshots as data URIs.

Related errors

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