docling-project/docling · error · DocumentLoadError

Could not initialize JATS backend for file with hash {self.d

Error message

Could not initialize JATS backend for file with hash {self.document_hash}.

What it means

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.

Source

Thrown at docling/backend/xml/jats_backend.py:193

            )
            self.tree: etree._ElementTree = etree.parse(
                self.path_or_stream, parser=parser
            )

            doc_info: etree.DocInfo = self.tree.docinfo
            if doc_info.system_url and any(
                kwd in doc_info.system_url for kwd in JATS_DTD_URL
            ):
                self.valid = True
                return
            for ent in doc_info.internalDTD.iterentities():
                if ent.system_url and any(
                    kwd in ent.system_url for kwd in JATS_DTD_URL
                ):
                    self.valid = True
                    return
        except Exception as exc:
            raise DocumentLoadError(
                f"Could not initialize JATS backend for file with hash {self.document_hash}."
            ) from exc

    @override
    def is_valid(self) -> bool:
        return self.valid

    @classmethod
    @override
    def supports_pagination(cls) -> bool:
        return False

    @override
    def unload(self):
        if isinstance(self.path_or_stream, BytesIO):
            self.path_or_stream.close()
        self.path_or_stream = None

View on GitHub (pinned to 61d76f1ff3)

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.

Example fix

# before
result = converter.convert(Path("article.xml"))  # DocumentLoadError

# after
from lxml import etree
etree.parse(str(jats_path))  # pre-validate; raises precise XML error first
result = converter.convert(jats_path)

Defensive patterns

Strategy: try-catch

Validate before calling

from lxml import etree

def jats_parses(path) -> bool:
    try:
        etree.parse(str(path))
        return True
    except Exception:
        return False

Try / catch

from docling.datamodel.base_docs import DocumentLoadError

try:
    result = converter.convert(jats_path)
except DocumentLoadError as e:
    logger.error("JATS load failed for %s: cause=%r", jats_path, e.__cause__)

Prevention

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.

When it happens

Trigger: 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.

Common situations: Truncated PubMed XML downloads; files with corrupted DOCTYPE declarations; non-XML content with a .xml extension; encoding mismatches.

Related errors

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