docling-project/docling · error · ValueError

OCR file {ocr_info.path} exceeds individual file size limit

Error message

OCR file {ocr_info.path} exceeds individual file size limit of {self.options.max_file_bytes} bytes

What it means

ValueError raised when a page's coordOCR member (HTML-ish OCR coordinate file) exceeds options.max_file_bytes after decompression. The OCR bytes are read with a bounded read(max_file_bytes+1) and rejected if over the cap — the same per-file bomb guard as images, applied to the OCR side of each page.

Source

Thrown at docling/backend/mets_gbs_backend.py:418

        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)."
            )
        ocr_file = cast(tarfile.ExFileObject, ocr_file)
        ocr_content = ocr_file.read(self.options.max_file_bytes + 1)
        if len(ocr_content) > self.options.max_file_bytes:
            raise ValueError(
                f"OCR file {ocr_info.path} exceeds individual file size limit of {self.options.max_file_bytes} bytes"
            )

        # Security: Track total bytes extracted
        self._total_bytes_extracted += len(ocr_content)
        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"
            )

        parser = etree.HTMLParser(no_network=True)
        ocr_root: etree._Element = etree.fromstring(ocr_content, parser=parser)

        line_cells: list[TextCell] = []
        word_cells: list[TextCell] = []

        page_div = ocr_root.xpath("//div[@class='ocr_page']")

View on GitHub (pinned to 61d76f1ff3)

Solutions

Raise MetsGbsBackendOptions(max_file_bytes=...) to exceed your largest OCR member.
Identify the offending member with `tar -tvzf book.tar.gz | grep -i ocr | sort -k3 -n | tail`.
Regenerate OCR at word level with fewer redundant elements, or simplify the hOCR, then repackage.
Keep a limit in place for untrusted archives.

Example fix

# before
result = converter.convert(mets_path)  # ValueError: OCR file exceeds limit

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

Defensive patterns

Strategy: validation

Validate before calling

import tarfile

def ocr_within_cap(tar_path: str, cap: int) -> bool:
    with tarfile.open(tar_path) as t:
        ocr = [m for m in t.getmembers() if 'ocr' in m.name.lower() or m.name.endswith(('.html', '.htm'))]
        return all(m.size <= cap for m in ocr) if ocr else True

Try / catch

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

Prevention

Measure OCR member sizes before conversion and set max_file_bytes above the max.
Simplify word-level hOCR for dense pages before packaging.
Record the failing page id when caught so regeneration can target it.

When it happens

Trigger: Converting a METS book where an hOCR/coordOCR file for some page is larger than max_file_bytes; trips during that page's conversion, after the image was already extracted and counted against the total.

Common situations: Very dense OCR files (word-level coordinates on dense scans), word-art or noisy pages generating huge hOCR, or a reduced max_file_bytes in options.

Related errors

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