docling-project/docling · error · DocumentLoadError

METS GBS backend could not load document {self.document_hash

Error message

METS GBS backend could not load document {self.document_hash}.

What it means

DocumentLoadError raised after the METS/GBS init scan completes: none of the .xml members scanned (within the size/count budgets) yielded a parseable METS root via _validate_mets_xml(). The backend therefore cannot find the document structure at all and refuses to load.

Source

Thrown at docling/backend/mets_gbs_backend.py:286

                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",
            "marc": "http://www.loc.gov/MARC21/slim",
        }

        file_info_by_id: dict[str, _FileInfo] = {}

        for filegrp in self.root_mets.xpath(".//mets:fileGrp", namespaces=ns):
            use_raw = filegrp.get("USE")
            try:
                use = _UseType(use_raw)

View on GitHub (pinned to 61d76f1ff3)

Solutions

  1. Confirm the input is actually a METS/GBS (Google Books) tar.gz; otherwise force the correct InputFormat/backend in format_options.
  2. Ensure the METS XML member ends with '.xml' (rename METS.XML/mets.xml.bak inside the archive).
  3. Validate the XML parses standalone: `tar -xzOf a.tar.gz '*.xml' | python -c 'import sys,lxml.etree as e; e.parse(sys.stdin)'`.
  4. Re-download the archive if truncated — partial gzip streams yield garbage members.

Example fix

# before
result = converter.convert('package.tar.gz')  # DocumentLoadError: could not load

# after (fix member naming inside the archive)
import tarfile
with tarfile.open('package.tar.gz') as src, tarfile.open('fixed.tar.gz', 'w:gz') as dst:
    for m in src.getmembers():
        data = src.extractfile(m).read() if m.isfile() else None
        m.name = m.name if m.name.endswith('.xml') else m.name + '.xml'
        dst.addfile(m, __import__('io').BytesIO(data) if data else None)
result = converter.convert('fixed.tar.gz')
Defensive patterns

Strategy: validation

Validate before calling

import tarfile
from lxml import etree

def has_mets_root(tar_path: str) -> bool:
    with tarfile.open(tar_path) as t:
        for m in t.getmembers():
            if m.name.endswith('.xml') and m.isfile():
                try:
                    root = etree.fromstring(t.extractfile(m).read())
                except etree.XMLSyntaxError:
                    continue
                if root.tag.startswith('{http://www.loc.gov/METS/}'):
                    return True
    return False

Try / catch

from docling.core.exceptions import DocumentLoadError
try:
    result = converter.convert(tar_path)
except DocumentLoadError as e:
    if 'METS GBS backend could not load' in str(e):
        log.error('%s is not a valid METS GBS package', tar_path)
        route_to_correct_backend(tar_path)

Prevention

When it happens

Trigger: Calling convert() on a .tar.gz that is not a METS GBS package — no member parses as METS XML (wrong backend selected by format detection), or the METS XML is malformed/renamed (e.g. .xml extension missing so it is skipped by the `member.name.endswith('.xml')` filter).

Common situations: Passing generic tar.gz or EPUB-like archives that get misrouted to the METS GBS backend, archives where METS.xml was uppercased or lacks the .xml suffix, or truncated downloads whose XML members fail to parse.

Related errors

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