docling-project/docling · error · ValueError

XML file {member.name} exceeds size limit of {self.options.m

Error message

XML file {member.name} exceeds size limit of {self.options.max_file_bytes} bytes

What it means

ValueError raised while scanning XML members of a METS/GBS tar archive during init: a member ending in .xml is read with a cap of max_file_bytes+1 bytes, and if more than max_file_bytes bytes come back the member is rejected. This is an individual-file decompression-bomb guard.

Source

Thrown at docling/backend/mets_gbs_backend.py:271

        )
        self.root_mets: etree._Element | None = None
        self.page_map: dict[int, _PageFiles] = {}
        self._total_bytes_extracted = 0
        member_count = 0

        for member in self._tar.getmembers():
            member_count += 1
            if member_count > self.options.max_member_count:
                raise ValueError(
                    f"Archive exceeds maximum member count limit of {self.options.max_member_count}"
                )

            if member.name.endswith(".xml"):
                file = self._tar.extractfile(member)
                if file is not None:
                    content = file.read(self.options.max_file_bytes + 1)
                    if len(content) > self.options.max_file_bytes:
                        raise ValueError(
                            f"XML file {member.name} exceeds size limit of {self.options.max_file_bytes} bytes"
                        )

                    self._total_bytes_extracted += len(content)
                    if self._total_bytes_extracted > self.options.max_total_bytes:
                        raise ValueError(
                            f"Archive exceeds maximum total extraction size of {self.options.max_total_bytes} bytes"
                        )

                    self.root_mets = self._validate_mets_xml(content)
                    if self.root_mets is not None:
                        break

        if self.root_mets is None:
            raise DocumentLoadError(
                f"METS GBS backend could not load document {self.document_hash}."
            )

View on GitHub (pinned to 61d76f1ff3)

Solutions

Increase the per-file cap: MetsGbsBackendOptions(max_file_bytes=...) sized to your largest legitimate XML member.
Check the member with `tar -tvzf file.tar.gz | sort -k3 -n` to see which XML is oversized and whether it is legitimate.
Strip or split unneeded giant XML sidecars from the archive before conversion.
Leave the guard on for untrusted archives — it prevents memory blowups from XML decompression bombs.

Example fix

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

# after
opts = MetsGbsBackendOptions(max_file_bytes=512 * 1024 * 1024)
# wire opts into the converter's format options, then:
result = converter.convert(mets_path)

Defensive patterns

Strategy: validation

Validate before calling

import tarfile

def largest_xml_within(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('.xml'))

Try / catch

try:
    result = converter.convert(mets_path)
except ValueError as e:
    if 'exceeds size limit' in str(e) and '.xml' in str(e):
        log.error('oversized XML member in %s: %s', mets_path, e)
        raise  # decide: raise the cap or reject the archive

Prevention

Set max_file_bytes above the largest XML member measured via tar -tvzf.
Keep oversized ALTO/OCR sidecars out of packages you ship to docling.
Retain the limit for untrusted archives to block XML bombs.

When it happens

Trigger: Converting a METS GBS archive containing an .xml member whose uncompressed size exceeds options.max_file_bytes (e.g. a multi-hundred-MB METS or OCR XML). The read(max_file_bytes+1) trick detects the overflow with a single bounded read.

Common situations: Books with extremely detailed OCR/ALTO XML, concatenated multi-volume METS files, hostile archives with a gzipped XML bomb, or a user-configured max_file_bytes that is too small for legitimately large metadata.

Related errors

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