docling-project/docling · error · ValueError

Image file {image_info.path} exceeds individual file size li

Error message

Image file {image_info.path} exceeds individual file size limit of {self.options.max_file_bytes} bytes

What it means

ValueError raised when a page image member inside a METS/GBS archive exceeds options.max_file_bytes after decompression. The image bytes are read with a max_file_bytes+1 cap and rejected if they exceed it — the per-file decompression-bomb guard applied specifically to page images during page conversion.

Source

Thrown at docling/backend/mets_gbs_backend.py:395

        ocr_info = self.page_map[page_no].coordOCR
        if image_info is None or ocr_info is None:
            _log.warning(
                f"Page {page_no} is missing an 'image' or 'coordOCR' fileGrp entry; "
                "skipping."
            )
            return None, None

        # Security: limit extraction size to prevent decompression bombs
        image_file = self._tar.extractfile(image_info.path)
        if image_file is None:
            raise RuntimeError(
                f"Archive member '{image_info.path}' is not a regular file "
                "(directory or symlink in tar)."
            )
        image_file = cast(tarfile.ExFileObject, image_file)
        image_data = image_file.read(self.options.max_file_bytes + 1)
        if len(image_data) > self.options.max_file_bytes:
            raise ValueError(
                f"Image file {image_info.path} exceeds individual file size limit of {self.options.max_file_bytes} bytes"
            )

        # Security: Track total bytes extracted
        self._total_bytes_extracted += len(image_data)
        if self._total_bytes_extracted > self.options.max_total_bytes:
            raise ValueError(
                f"Total extracted data exceeds maximum limit of {self.options.max_total_bytes} bytes"
            )

        buf = BytesIO(image_data)
        im: PILImage = Image.open(buf)

        ocr_file = self._tar.extractfile(ocr_info.path)
        if ocr_file is None:
            raise RuntimeError(
                f"Archive member '{ocr_info.path}' is not a regular file "
                "(directory or symlink in tar)."

View on GitHub (pinned to 61d76f1ff3)

Solutions

  1. Raise MetsGbsBackendOptions(max_file_bytes=...) above your largest page image size.
  2. Downsample page images before packaging (`mogrify -resize 3000x ...`).
  3. Check which page is oversized via `tar -tvzf book.tar.gz | sort -k3 -n | tail`.
  4. Keep the limit for untrusted archives; only raise it for trusted internal digitization pipelines.

Example fix

# before
result = converter.convert(mets_path)  # ValueError: image exceeds size limit

# after
opts = MetsGbsBackendOptions(max_file_bytes=256 * 1024 * 1024)
# wire into converter format options, then convert
result = converter.convert(mets_path)
Defensive patterns

Strategy: validation

Validate before calling

import tarfile

def images_within_cap(tar_path: str, cap: int) -> bool:
    with tarfile.open(tar_path) as t:
        return all(m.size <= cap for m in t.getmembers() if m.name.endswith(('.png', '.jpg', '.jpeg')))

Try / catch

try:
    result = converter.convert(mets_path)
except ValueError as e:
    if 'exceeds individual file size limit' in str(e):
        opts = MetsGbsBackendOptions(max_file_bytes=CAP)
        result = converter_with(opts).convert(mets_path)
    else:
        raise

Prevention

When it happens

Trigger: Converting a METS book whose page scans (PNG/JPEG) are larger than the configured max_file_bytes; trips in _get_page_cells/get_page_image when that page is processed, not at init.

Common situations: High-resolution scans (600dpi TIFF-as-PNG pages), archives from labs with huge plates/images, or a lowered max_file_bytes setting. Legitimate large scans are the usual cause rather than an attack.

Related errors

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