docling-project/docling · warning · ValueError

Downloaded data exceeds size limit

Error message

Downloaded data exceeds size limit

What it means

While streaming a remote image, the total bytes received crossed max_remote_image_bytes (default 20 MiB). This triggers when the content-length header was absent or understated (chunked responses) so the pre-flight check [80] could not catch it. The download is aborted mid-stream to bound memory usage.

Source

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

            session.hooks["response"].append(_check_redirect_safety)

            response = session.get(
                src_loc, stream=True, headers=headers, timeout=(5, 30)
            )
            response.raise_for_status()

            content_length = response.headers.get("content-length")
            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."

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Raise options max_remote_image_bytes to cover the real image sizes you expect.
2. Point the document at a hosted, correctly-sized variant of the image.
3. If the remote resource is untrusted, keep the limit and accept that the image is skipped (create_image_ref warns and returns None).
4. Host the asset locally and use enable_local_fetch with base_path instead of remote fetching.

Example fix

# before
conv_opts = PipelineOptions()  # default 20 MiB remote image cap

# after
from docling.datamodel.pipeline_options import HtmlPipelineOptions
html_opts = HtmlPipelineOptions()
html_opts.max_remote_image_bytes = 200 * 1024 * 1024

import urllib.request

def remote_image_within_limit_streamed(url: str, max_bytes: int) -> bool:
    # no reliable pre-check when content-length is absent; HEAD first, else expect abort
    req = urllib.request.Request(url, method="HEAD")
    with urllib.request.urlopen(req, timeout=10) as resp:
        cl = resp.headers.get("content-length")
        return cl is None or int(cl) <= max_bytes

try:
    data = loader.load_image_data(src, base_path)
except ValueError as e:
    logger.warning("image %s exceeded streamed size limit: %s", src, e)
    data = None

When it happens

Trigger: Remote image fetched with enable_remote_fetch=True where the server omits or lies about content-length (chunked transfer encoding), and the accumulated 8192-byte chunks exceed max_remote_image_bytes.

Common situations: CDNs using chunked encoding; servers that ignore the Range request header; dynamically generated images with unknown size; malicious servers deliberately hiding size.

Related errors

• Resource size exceeds limit: {content_length} bytes
• URL must contain a valid hostname
• Cannot resolve hostname: {hostname}
• Access to restricted IP address not allowed: {ip}
• Fetching remote resources is only allowed when set explicitl

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