docling-project/docling · error · ValueError

Archive exceeds maximum member count limit of {self.options.

Error message

Archive exceeds maximum member count limit of {self.options.max_member_count}

What it means

ValueError raised during METS/GBS archive validation: while scanning tar members during init, the backend counts entries and aborts as soon as the count exceeds options.max_member_count. This is a deliberate decompression-bomb / resource-exhaustion guard limiting how many members a single .tar.gz may contain.

Source

Thrown at docling/backend/mets_gbs_backend.py:262

    ):
        if options is None:
            options = MetsGbsBackendOptions()
        super().__init__(in_doc, path_or_stream, options)
        self.options: MetsGbsBackendOptions
        self._tar: tarfile.TarFile = (
            tarfile.open(name=self.path_or_stream, mode="r:gz")
            if isinstance(self.path_or_stream, Path)
            else tarfile.open(fileobj=self.path_or_stream, mode="r:gz")
        )
        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"
                        )

View on GitHub (pinned to 61d76f1ff3)

Solutions

Raise the limit: pass MetsGbsBackendOptions(max_member_count=<N>) large enough for your archives.
Inspect the archive (`tar -tzf file.tar.gz | wc -l`) to confirm the true member count and detect padding/pollution.
Split oversized archives into per-volume METS packages that each fit under the limit.
Keep the guard enabled for untrusted input — it exists to prevent resource exhaustion.

Example fix

# before
result = converter.convert(mets_path)  # ValueError: member count

# after
from docling.backend.mets_gbs_backend import MetsGbsBackendOptions
opts = MetsGbsBackendOptions(max_member_count=20000)
converter = DocumentConverter(format_options={InputFormat.METS_GBS: PdfPipelineOptions(backend_options=opts)})
result = converter.convert(mets_path)

Defensive patterns

Strategy: validation

Validate before calling

import tarfile

def member_count_ok(tar_path: str, limit: int) -> bool:
    with tarfile.open(tar_path) as t:
        return len(t.getmembers()) <= limit

Try / catch

try:
    result = converter.convert(mets_path)
except ValueError as e:
    if 'maximum member count' in str(e):
        opts = MetsGbsBackendOptions(max_member_count=REASONABLE_CAP)
        result = converter_with(opts).convert(mets_path)
    else:
        raise

Prevention

Size max_member_count from your largest legitimate archive before batch runs.
Count members (`tar -tzf f | wc -l`) during ingest validation.
Split mega-archives into per-volume packages instead of raising limits blindly.

When it happens

Trigger: Calling convert() on a METS GBS .tar.gz whose member count exceeds the configured max_member_count (default defined in MetsGbsBackendOptions). The check trips on member number max_member_count+1 regardless of member sizes.

Common situations: Large multi-volume book archives, archives with many small per-page files, or hostile/corrupted archives padded with thousands of members. Also when defaults were lowered or a user set a very small max_member_count.

Related errors

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