{"record":{"id":"4daa79e62357c1f2","repo":"docling-project/docling","slug":"cannot-convert-doc-with-self-document-hash-becau-4daa79","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/msexcel_backend.py","lineNumber":505,"sourceCode":"        Raises:\n            RuntimeError: Unable to run the conversion since the backend object failed to\n            initialize.\n\n        Returns:\n            The DoclingDocument object representing the Excel workbook.\n        \"\"\"\n        origin = DocumentOrigin(\n            filename=self.file.name or \"file.xlsx\",\n            mimetype=FormatToMimeType[self.input_format][0],\n            binary_hash=self.document_hash,\n        )\n\n        doc = DoclingDocument(name=self.file.stem or \"file.xlsx\", origin=origin)\n\n        if self.is_valid():\n            doc = self._convert_workbook(doc)\n        else:\n            raise RuntimeError(\n                f\"Cannot convert doc with {self.document_hash} because the backend failed to init.\"\n            )\n\n        return doc\n\n    def _convert_workbook(self, doc: DoclingDocument) -> DoclingDocument:\n        \"\"\"Parse the Excel workbook and attach its structure to a DoclingDocument.\n\n        Args:\n            doc: A DoclingDocument object.\n\n        Returns:\n            A DoclingDocument object with the parsed items.\n        \"\"\"\n\n        if self.workbook is not None:\n            sheet_names_filter: list[str] | None = (\n                self.options.sheet_names","sourceCodeStart":487,"sourceCodeEnd":523,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/msexcel_backend.py#L487-L523","documentation":"RuntimeError raised by MsExcelDocumentBackend.convert() when is_valid() is False, i.e. the workbook was never successfully loaded in init (or load failed and the error was swallowed). It is the post-init state guard: convert() builds the DoclingDocument skeleton first, then refuses to parse a workbook it does not have.","triggerScenarios":"Calling convert() after init failed without propagating the DocumentLoadError — typically in custom code that catches the load error and continues, or reuses a backend object whose load failed. The normal DocumentConverter path raises the load error first, so this mainly appears in manual backend usage.","commonSituations":"Custom pipelines constructing backends directly, retry logic that catches the first error but calls convert anyway, or subclass flows where init error handling suppresses exceptions.","solutions":["Always check backend.is_valid() before convert() when driving backends manually.","Fix the underlying load failure (corrupt/unsupported workbook — see the Excel DocumentLoadError).","In batch jobs, catch this RuntimeError, log the file, and continue with the next document."],"exampleFix":"# before\nbackend = MsExcelDocumentBackend(in_doc, path)\ndoc = backend.convert()  # RuntimeError\n\n# after\nbackend = MsExcelDocumentBackend(in_doc, path)\nif not backend.is_valid():\n    logger.error('invalid workbook: %s', path)\n    return None\ndoc = backend.convert()","handlingStrategy":"validation","validationCode":"backend = MsExcelDocumentBackend(in_doc, path)\nif not backend.is_valid():\n    skip(path)  # never call convert() on an invalid backend","typeGuard":"def backend_ready(backend) -> bool:\n    return backend.is_valid()","tryCatchPattern":"if not backend.is_valid():\n    log.warning('skipping %s: Excel backend not initialized', path)\n    return None\ntry:\n    doc = backend.convert()\nexcept RuntimeError:\n    log.error('convert() on invalid Excel backend for %s', path)\n    return None","preventionTips":["Gate convert() behind is_valid() whenever you construct backends yourself.","Do not swallow the init-time DocumentLoadError and continue.","Batch runners should catch-and-log per document to keep the queue moving."],"tags":["excel","state-check","guard"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}