docling-project/docling · error · RuntimeError

Cannot convert doc with {self.document_hash} because the bac

Error message

Cannot convert doc with {self.document_hash} because the backend failed to init.

What it means

RuntimeError raised by OdtDocumentBackend.convert() when is_valid() is False — the shared _OdfBaseBackend constructor either failed to load the document (which usually raises earlier) or the validity flag was never set. It guards convert() against running on an uninitialized odf_obj body.

Source

Thrown at docling/backend/opendocument_backend.py:1498

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

    @classmethod
    @override
    def supported_formats(cls) -> set[InputFormat]:
        return {InputFormat.ODT}

    @override
    def convert(self) -> DoclingDocument:
        origin = DocumentOrigin(
            filename=self.file.name or "file",
            mimetype="application/vnd.oasis.opendocument.text",
            binary_hash=self.document_hash,
        )
        doc = DoclingDocument(name=self.file.stem or "file", origin=origin)
        if not self.is_valid():
            raise RuntimeError(
                f"Cannot convert doc with {self.document_hash} because the backend failed to init."
            )

        self._walk(self.odf_obj.body.children, parent=None, doc=doc)
        return doc

    def _walk(
        self,
        elements: list[Any],
        parent: NodeItem | None,
        doc: DoclingDocument,
    ) -> None:
        _add_odf_children(
            doc,
            elements,
            parent=parent,
            content_layer=None,
            odf_obj=self.odf_obj,

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Check backend.is_valid() before convert().
2. Do not suppress constructor exceptions — let DocumentLoadError/RuntimeError from loading propagate instead of calling convert() on a broken backend.
3. Re-run with the source file present and readable for the whole conversion window.

Example fix

# before
doc = backend.convert()

# after
if not backend.is_valid():
    raise ValueError('ODT backend not initialized; load failed earlier')
doc = backend.convert()

if not backend.is_valid():
    raise ValueError('ODT backend not initialized')

if backend.is_valid():
    doc = backend.convert()
else:
    raise ValueError('ODT load failed; see constructor error')

When it happens

Trigger: Calling convert() on an ODT backend instance whose load path left self.valid False — e.g. subclass misuse, or code that swallows the constructor's RuntimeError and continues.

Common situations: Wrapper code that constructs backends in try/except and calls convert() unconditionally; race conditions where the file was deleted between construction and conversion.

Related errors

• Cannot convert doc with {self.document_hash} because the bac
• Cannot convert md with {self.document_hash} because the back
• Cannot convert doc with {self.document_hash} because the bac

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