What causes "Resource size exceeds limit: {content_length} bytes" in docling-project/docling?

Raise the limit: set max_remote_image_bytes (e.g. 50*1024*1024) in your pipeline options if the images are legitimately large.

docling-project/docling · warning · ValueError

Resource size exceeds limit: {content_length} bytes

Error message

Resource size exceeds limit: {content_length} bytes

What it means

The HTML/Markdown backend's ImageResourceLoader refuses to download a remote image because the HTTP response declares a content-length larger than max_remote_image_bytes (default 20 MiB, wired from pipeline options). It is a defense against decompression/quota attacks from untrusted documents. The check happens before any body is streamed, so no bytes are downloaded.

Source

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

                    redirect_url = response.headers.get("location")
                    if redirect_url:
                        # Handle relative redirects
                        if not redirect_url.startswith(("http://", "https://")):
                            redirect_url = urljoin(response.url, redirect_url)

                        # Validate the redirect target
                        validate_url_safety(redirect_url)

            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."

View on GitHub (pinned to 61d76f1ff3)

Solutions

Raise the limit: set max_remote_image_bytes (e.g. 50*1024*1024) in your pipeline options if the images are legitimately large.
If the image is genuinely needed smaller, pre-process the source document to reference resized images.
If the URL is wrong or points at an unintended huge asset, fix or remove the src in the input document.
Accept the degraded conversion: create_image_ref already warns and skips oversized images, so verify whether the missing image actually matters for your output.

Example fix

# before
pipeline_options = HtmlPipelineOptions()
pipeline_options.do_images_enhance = True

# after
pipeline_options = HtmlPipelineOptions()
pipeline_options.max_remote_image_bytes = 100 * 1024 * 1024

Defensive patterns

Strategy: try-catch

Validate before calling

import urllib.request

def remote_image_within_limit(url: str, max_bytes: int) -> bool:
    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 / catch

try:
    img_ref = loader.load_image_ref(src, base_path)
except ValueError as e:  # covers both size-limit ValueErrors
    logger.warning("skipping oversized image %s: %s", src, e)
    img_ref = None

Prevention

Set max_remote_image_bytes to the largest legitimate image in your corpus before converting.
Audit documents for huge remote assets during ingestion and downscale or reject them early.
Remember create_image_ref already downgrades this to a warning; only direct load_image_data calls raise.

When it happens

Trigger: Converting an HTML or Markdown document whose <img src>/![]() points at an http(s) URL whose server returns a content-length header greater than options.max_remote_image_bytes; only fires when enable_remote_fetch=True already allowed the request.

Common situations: Documents embedding very large photographs or print-resolution scans (common in report-heavy HTML exports); a low custom max_remote_image_bytes set by a security team; servers reporting total file size even when a Range header was sent.

Related errors

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