{"record":{"id":"cd357282e2a56241","repo":"docling-project/docling","slug":"could-not-initialize-jats-backend-for-file-with-ha","errorCode":null,"errorMessage":"Could not initialize JATS backend for file with hash {self.document_hash}.","messagePattern":"Could not initialize JATS backend for file with hash (.+?)\\.","errorType":"exception","errorClass":"DocumentLoadError","httpStatus":null,"severity":"error","filePath":"docling/backend/xml/jats_backend.py","lineNumber":193,"sourceCode":"            )\n            self.tree: etree._ElementTree = etree.parse(\n                self.path_or_stream, parser=parser\n            )\n\n            doc_info: etree.DocInfo = self.tree.docinfo\n            if doc_info.system_url and any(\n                kwd in doc_info.system_url for kwd in JATS_DTD_URL\n            ):\n                self.valid = True\n                return\n            for ent in doc_info.internalDTD.iterentities():\n                if ent.system_url and any(\n                    kwd in ent.system_url for kwd in JATS_DTD_URL\n                ):\n                    self.valid = True\n                    return\n        except Exception as exc:\n            raise DocumentLoadError(\n                f\"Could not initialize JATS backend for file with hash {self.document_hash}.\"\n            ) from exc\n\n    @override\n    def is_valid(self) -> bool:\n        return self.valid\n\n    @classmethod\n    @override\n    def supports_pagination(cls) -> bool:\n        return False\n\n    @override\n    def unload(self):\n        if isinstance(self.path_or_stream, BytesIO):\n            self.path_or_stream.close()\n        self.path_or_stream = None\n","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/xml/jats_backend.py#L175-L211","documentation":"The JATS backend constructor failed while reading/parsing the document (lxml etree setup, DTD inspection, or I/O) and wraps the cause in DocumentLoadError. The try block covers XML parsing setup and examining doc_info/internal DTD entities to decide validity; any exception there is fatal for backend init.","triggerScenarios":"Constructing JatsBackend on malformed XML, a file that cannot be read, or content whose DTD/doctype declaration makes lxml's parser raise (e.g. entity expansion issues, invalid syntax) — caught by 'except Exception' and re-raised as DocumentLoadError chained to the original error.","commonSituations":"Truncated PubMed XML downloads; files with corrupted DOCTYPE declarations; non-XML content with a .xml extension; encoding mismatches.","solutions":["Inspect the chained cause (__cause__) — it names the real lxml/IO error.","Validate the file first: python -c 'from lxml import etree; etree.parse(f)' to reproduce and fix the XML.","Re-download or repair the source document; check it starts with a proper <?xml ...?> and well-formed root.","Catch DocumentLoadError in batch pipelines and quarantine the bad file."],"exampleFix":"# before\nresult = converter.convert(Path(\"article.xml\"))  # DocumentLoadError\n\n# after\nfrom lxml import etree\netree.parse(str(jats_path))  # pre-validate; raises precise XML error first\nresult = converter.convert(jats_path)","handlingStrategy":"try-catch","validationCode":"from lxml import etree\n\ndef jats_parses(path) -> bool:\n    try:\n        etree.parse(str(path))\n        return True\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"from docling.datamodel.base_docs import DocumentLoadError\n\ntry:\n    result = converter.convert(jats_path)\nexcept DocumentLoadError as e:\n    logger.error(\"JATS load failed for %s: cause=%r\", jats_path, e.__cause__)","preventionTips":["Pre-validate XML well-formedness at ingestion.","Always log e.__cause__ — it carries the actual lxml error.","Quarantine files that fail load in batch corpora."],"tags":["jats","xml","document-load","parsing","lxml"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}