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 in MsWordDocumentBackend.convert() when is_valid() returns False, meaning the backend accepted construction but the underlying docx_obj never loaded (or failed validation). It signals that convert() was called on a backend in a failed-init state rather than the load error itself surfacing.

Source

Thrown at docling/backend/msword_backend.py:524

            filename=self.file.name or "file",
            mimetype=FormatToMimeType[self.input_format][0],
            binary_hash=self.document_hash,
        )

        doc = DoclingDocument(name=self.file.stem or "file", origin=origin)
        if self.is_valid():
            assert self.docx_obj is not None
            # Reset mappings for a fresh conversion pass
            self.paragraph_comment_map.clear()
            self.paragraph_to_items.clear()
            doc, _ = self._walk_linear(self.docx_obj.element.body, doc)
            self._add_header_footer(self.docx_obj, doc)
            # Add comments and link them to annotated paragraphs
            self._add_comments(self.docx_obj, doc)

            return doc
        else:
            raise RuntimeError(
                f"Cannot convert doc with {self.document_hash} because the backend failed to init."
            )

    @staticmethod
    def load_msword_file(
        path_or_stream: BytesIO | Path, document_hash: str
    ) -> DocxDocument:
        try:
            if isinstance(path_or_stream, Path):
                with zipfile.ZipFile(path_or_stream) as archive:
                    if _is_strict_ooxml(archive):
                        return Document(_normalize_strict_ooxml(archive))
                return Document(str(path_or_stream))
            elif isinstance(path_or_stream, BytesIO):
                with zipfile.ZipFile(path_or_stream) as archive:
                    if _is_strict_ooxml(archive):
                        return Document(_normalize_strict_ooxml(archive))
                path_or_stream.seek(0)

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Check backend.is_valid() before calling convert().
2. Verify the file is a real docx: file example.docx should report 'Microsoft Word 2007+'; open it in Word/LibreOffice.
3. Convert legacy .doc content to real .docx (docling shells out for DOC, so ensure libreoffice is installed if feeding .doc).
4. Handle the underlying DocumentLoadError from the constructor instead of proceeding to convert().

Example fix

# before
doc = backend.convert()  # RuntimeError: backend failed to init

# after
if backend.is_valid():
    doc = backend.convert()
else:
    raise ValueError('input is not a valid Word document')

if not backend.is_valid():
    raise ValueError('Word backend not valid; document failed to load')

if not backend.is_valid():
    raise ValueError(f'{backend.document_hash}: invalid Word document')
result = backend.convert()

When it happens

Trigger: Calling .convert() on a MsWordDocumentBackend whose Document load produced an invalid object — e.g. the file exists but is not a readable OOXML package — and the constructor's failure path left the backend marked invalid.

Common situations: Renamed files (a .txt or legacy .doc mislabeled as .docx), empty files, or user code that ignores constructor exceptions and calls convert() anyway.

Related errors

• Cannot convert doc with {self.document_hash} because the bac
• Libreoffice not found
• LibreOffice is required to convert a .{source_suffix} file t
• LibreOffice did not produce the expected output: {converted_
• Cannot convert md with {self.document_hash} because the back

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