docling-project/docling · error · ValueError

Archive exceeds maximum total extraction size of {self.optio

Error message

Archive exceeds maximum total extraction size of {self.options.max_total_bytes} bytes

What it means

ValueError raised during METS/GBS init when the running sum of bytes extracted from XML members exceeds options.max_total_bytes. Each XML member read is added to self._total_bytes_extracted and the cumulative total is capped, preventing aggregate decompression-bomb expansion across many members.

Source

Thrown at docling/backend/mets_gbs_backend.py:277

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

        ns = {
            "mets": "http://www.loc.gov/METS/",
            "xlink": "http://www.w3.org/1999/xlink",
            "xsi": "http://www.w3.org/2001/XMLSchema-instance",
            "gbs": "http://books.google.com/gbs",
            "premis": "info:lc/xmlns/premis-v2",

View on GitHub (pinned to 61d76f1ff3)

Solutions

Raise MetsGbsBackendOptions(max_total_bytes=...) to comfortably exceed the archive's total uncompressed XML size.
Measure the real total: `tar -xzOf file.tar.gz '*.xml' | wc -c` (bounded) or inspect member sizes with `tar -tvzf`.
Split the archive so each package stays under the budget.
Treat an unexpectedly huge total on untrusted input as a red flag rather than a configuration problem.

Example fix

# before
result = converter.convert(mets_path)  # ValueError: total extraction size

# after
opts = MetsGbsBackendOptions(max_total_bytes=4 * 1024 * 1024 * 1024)
# pass opts via format options, then convert
result = converter.convert(mets_path)

Defensive patterns

Strategy: validation

Validate before calling

import tarfile

def xml_total_within(tar_path: str, cap: int) -> bool:
    with tarfile.open(tar_path) as t:
        return sum(m.size for m in t.getmembers() if m.name.endswith('.xml')) <= cap

Try / catch

try:
    result = converter.convert(mets_path)
except ValueError as e:
    if 'maximum total extraction size' in str(e):
        opts = MetsGbsBackendOptions(max_total_bytes=BUDGET)
        result = converter_with(opts).convert(mets_path)
    else:
        raise

Prevention

Budget max_total_bytes against total uncompressed XML size, not file count.
Measure totals during ingest with tar member-size sums.
Split bundles whose metadata alone exceeds budget.

When it happens

Trigger: Converting an archive whose combined XML member sizes exceed max_total_bytes — either many medium-sized XML files or several large ones. Trips during the member scan in __init__, before the METS root is even identified.

Common situations: Multi-book bundles, archives that include both METS and bulky ALTO/page OCR XML, or a lowered default max_total_bytes. Also malicious archives with many expanding members.

Related errors

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