{"record":{"id":"f4955b142dd510fe","repo":"docling-project/docling","slug":"mets-gbs-backend-could-not-load-document-self-doc","errorCode":null,"errorMessage":"METS GBS backend could not load document {self.document_hash}.","messagePattern":"METS GBS backend could not load document (.+?)\\.","errorType":"exception","errorClass":"DocumentLoadError","httpStatus":null,"severity":"error","filePath":"docling/backend/mets_gbs_backend.py","lineNumber":286,"sourceCode":"                if file is not None:\n                    content = file.read(self.options.max_file_bytes + 1)\n                    if len(content) > self.options.max_file_bytes:\n                        raise ValueError(\n                            f\"XML file {member.name} exceeds size limit of {self.options.max_file_bytes} bytes\"\n                        )\n\n                    self._total_bytes_extracted += len(content)\n                    if self._total_bytes_extracted > self.options.max_total_bytes:\n                        raise ValueError(\n                            f\"Archive exceeds maximum total extraction size of {self.options.max_total_bytes} bytes\"\n                        )\n\n                    self.root_mets = self._validate_mets_xml(content)\n                    if self.root_mets is not None:\n                        break\n\n        if self.root_mets is None:\n            raise DocumentLoadError(\n                f\"METS GBS backend could not load document {self.document_hash}.\"\n            )\n\n        ns = {\n            \"mets\": \"http://www.loc.gov/METS/\",\n            \"xlink\": \"http://www.w3.org/1999/xlink\",\n            \"xsi\": \"http://www.w3.org/2001/XMLSchema-instance\",\n            \"gbs\": \"http://books.google.com/gbs\",\n            \"premis\": \"info:lc/xmlns/premis-v2\",\n            \"marc\": \"http://www.loc.gov/MARC21/slim\",\n        }\n\n        file_info_by_id: dict[str, _FileInfo] = {}\n\n        for filegrp in self.root_mets.xpath(\".//mets:fileGrp\", namespaces=ns):\n            use_raw = filegrp.get(\"USE\")\n            try:\n                use = _UseType(use_raw)","sourceCodeStart":268,"sourceCodeEnd":304,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/mets_gbs_backend.py#L268-L304","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Confirm the input is actually a METS/GBS (Google Books) tar.gz; otherwise force the correct InputFormat/backend in format_options.","Ensure the METS XML member ends with '.xml' (rename METS.XML/mets.xml.bak inside the archive).","Validate the XML parses standalone: `tar -xzOf a.tar.gz '*.xml' | python -c 'import sys,lxml.etree as e; e.parse(sys.stdin)'`.","Re-download the archive if truncated — partial gzip streams yield garbage members."],"exampleFix":"# before\nresult = converter.convert('package.tar.gz')  # DocumentLoadError: could not load\n\n# after (fix member naming inside the archive)\nimport tarfile\nwith tarfile.open('package.tar.gz') as src, tarfile.open('fixed.tar.gz', 'w:gz') as dst:\n    for m in src.getmembers():\n        data = src.extractfile(m).read() if m.isfile() else None\n        m.name = m.name if m.name.endswith('.xml') else m.name + '.xml'\n        dst.addfile(m, __import__('io').BytesIO(data) if data else None)\nresult = converter.convert('fixed.tar.gz')","handlingStrategy":"validation","validationCode":"import tarfile\nfrom lxml import etree\n\ndef has_mets_root(tar_path: str) -> bool:\n    with tarfile.open(tar_path) as t:\n        for m in t.getmembers():\n            if m.name.endswith('.xml') and m.isfile():\n                try:\n                    root = etree.fromstring(t.extractfile(m).read())\n                except etree.XMLSyntaxError:\n                    continue\n                if root.tag.startswith('{http://www.loc.gov/METS/}'):\n                    return True\n    return False","typeGuard":null,"tryCatchPattern":"from docling.core.exceptions import DocumentLoadError\ntry:\n    result = converter.convert(tar_path)\nexcept DocumentLoadError as e:\n    if 'METS GBS backend could not load' in str(e):\n        log.error('%s is not a valid METS GBS package', tar_path)\n        route_to_correct_backend(tar_path)","preventionTips":["Force the correct InputFormat in format_options when extensions are ambiguous.","Ensure the METS member carries a lowercase .xml suffix.","Verify gzip integrity (`gzip -t`) of downloaded archives before conversion."],"tags":["mets","document-load","archive","format-detection"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}