docling-project/docling · error · RuntimeError

Invalid document with hash {self.document_hash}

Error message

Invalid document with hash {self.document_hash}

What it means

Raised by XbrlBackend.convert() when the backend was never successfully initialized — is_valid() is False or model_xbrl is None. It indicates convert() was called on a backend whose __init__ failed or was never run, which normally cannot happen through the public DocumentConverter API because failed backends are rejected during selection.

Source

Thrown at docling/backend/xml/xbrl_backend.py:252

            self._created_links.add(key)
            self._links.append(
                GraphLink(
                    label=label,
                    source_cell_id=src,
                    target_cell_id=tgt,
                )
            )

    @override
    def convert(self) -> DoclingDocument:
        """Convert XBRL document to DoclingDocument using Arelle library.

        This is a placeholder implementation that creates a basic document structure.
        Full XBRL parsing using Arelle library can be implemented here.
        """
        _log.debug("Starting XBRL instance conversion...")
        if not self.is_valid() or not self.model_xbrl:
            raise RuntimeError(f"Invalid document with hash {self.document_hash}")

        origin = DocumentOrigin(
            filename=self.file.name or "file",
            mimetype="application/xml",
            binary_hash=self.document_hash,
        )
        doc = DoclingDocument(name=self.file.stem or "file", origin=origin)
        doc_name = doc.name

        # Some metadata
        doc_type: str = ""
        doc_org: str = ""
        doc_period: str = ""
        for fact in self.model_xbrl.facts:
            if fact.qname.localName == "DocumentType" and fact.value:
                doc_type = fact.value
            if fact.qname.localName == "EntityRegistrantName" and fact.value:
                doc_org = fact.value

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Do not call convert() unless is_valid() returns True; check it first.
2. Use the public DocumentConverter API, which discards invalid backends and picks another one instead of letting you call convert() on them.
3. Create a fresh backend instance per document file.
4. If it happens via DocumentConverter, verify the file actually parses as XBRL (see errors 100-102).

Example fix

// before
backend = XbrlBackend(file, options)
doc = backend.convert()  # RuntimeError if init failed

// after
backend = XbrlBackend(file, options)
if backend.is_valid():
    doc = backend.convert()

backend = XbrlBackend(file, options)
if not backend.is_valid():
    raise RuntimeError('backend init failed; do not call convert()')

def backend_ready(b) -> bool:
    return b.is_valid() and b.model_xbrl is not None

try:
    doc = backend.convert()
except RuntimeError as e:
    if 'Invalid document' in str(e):
        reinitialize_backend_with_valid_file()

When it happens

Trigger: Constructing XbrlBackend directly and calling convert() after a failed load; calling convert() on a backend instance whose initialization raised (leaving valid=False); programmatic reuse of a backend object across files.

Common situations: Code that instantiates backends manually (bypassing DocumentConverter's selection logic) or caches backend objects; test harnesses that construct the backend with stub files.

Related errors

• path_or_stream must be Path or BytesIO
• Invalid or unreadable XBRL file
• Document is not an XBRL instance
• XBRL loaded with errors: {model.errors}
• Could not initialize XBRL backend for file with hash {self.d

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