{"record":{"id":"3620ff7bb6580081","repo":"docling-project/docling","slug":"cannot-convert-doc-with-self-document-hash-becau-3620ff","errorCode":null,"errorMessage":"Cannot convert doc with {self.document_hash} because the backend failed to init.","messagePattern":"Cannot convert doc with (.+?) because the backend failed to init\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/backend/msword_backend.py","lineNumber":524,"sourceCode":"            filename=self.file.name or \"file\",\n            mimetype=FormatToMimeType[self.input_format][0],\n            binary_hash=self.document_hash,\n        )\n\n        doc = DoclingDocument(name=self.file.stem or \"file\", origin=origin)\n        if self.is_valid():\n            assert self.docx_obj is not None\n            # Reset mappings for a fresh conversion pass\n            self.paragraph_comment_map.clear()\n            self.paragraph_to_items.clear()\n            doc, _ = self._walk_linear(self.docx_obj.element.body, doc)\n            self._add_header_footer(self.docx_obj, doc)\n            # Add comments and link them to annotated paragraphs\n            self._add_comments(self.docx_obj, doc)\n\n            return doc\n        else:\n            raise RuntimeError(\n                f\"Cannot convert doc with {self.document_hash} because the backend failed to init.\"\n            )\n\n    @staticmethod\n    def load_msword_file(\n        path_or_stream: BytesIO | Path, document_hash: str\n    ) -> DocxDocument:\n        try:\n            if isinstance(path_or_stream, Path):\n                with zipfile.ZipFile(path_or_stream) as archive:\n                    if _is_strict_ooxml(archive):\n                        return Document(_normalize_strict_ooxml(archive))\n                return Document(str(path_or_stream))\n            elif isinstance(path_or_stream, BytesIO):\n                with zipfile.ZipFile(path_or_stream) as archive:\n                    if _is_strict_ooxml(archive):\n                        return Document(_normalize_strict_ooxml(archive))\n                path_or_stream.seek(0)","sourceCodeStart":506,"sourceCodeEnd":542,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/msword_backend.py#L506-L542","documentation":"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.","triggerScenarios":"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.","commonSituations":"Renamed files (a .txt or legacy .doc mislabeled as .docx), empty files, or user code that ignores constructor exceptions and calls convert() anyway.","solutions":["Check backend.is_valid() before calling convert().","Verify the file is a real docx: file example.docx should report 'Microsoft Word 2007+'; open it in Word/LibreOffice.","Convert legacy .doc content to real .docx (docling shells out for DOC, so ensure libreoffice is installed if feeding .doc).","Handle the underlying DocumentLoadError from the constructor instead of proceeding to convert()."],"exampleFix":"# before\ndoc = backend.convert()  # RuntimeError: backend failed to init\n\n# after\nif backend.is_valid():\n    doc = backend.convert()\nelse:\n    raise ValueError('input is not a valid Word document')","handlingStrategy":"validation","validationCode":"if not backend.is_valid():\n    raise ValueError('Word backend not valid; document failed to load')","typeGuard":null,"tryCatchPattern":"if not backend.is_valid():\n    raise ValueError(f'{backend.document_hash}: invalid Word document')\nresult = backend.convert()","preventionTips":["Always pair construction with an is_valid() check before convert()","Let constructor load errors (DocumentLoadError) surface instead of swallowing them","Validate the file is a real OOXML zip before conversion"],"tags":["docx","invalid-input","state-check"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}