{"record":{"id":"34976d9526d38bf3","repo":"docling-project/docling","slug":"cannot-convert-doc-with-self-document-hash-becau-34976d","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/email_backend.py","lineNumber":286,"sourceCode":"        \"\"\"Return one display label per attachment (name, optional content type).\n\n        Only attachment metadata is surfaced; the encoded payload is never\n        included, matching how ``.eml`` attachment content is excluded.\n        \"\"\"\n        assert self.mail is not None\n\n        labels: list[str] = []\n        for index, attachment in enumerate(self.mail.attachments or []):\n            filename = (attachment.get(\"filename\") or \"\").strip()\n            if not filename:\n                filename = f\"attachment-{index + 1}\"\n            content_type = (attachment.get(\"mail_content_type\") or \"\").strip()\n            labels.append(f\"{filename} ({content_type})\" if content_type else filename)\n        return labels\n\n    def convert(self) -> DoclingDocument:\n        if not self.is_valid() or self.mail is None:\n            raise RuntimeError(\n                f\"Cannot convert doc with {self.document_hash} because the backend failed to init.\"\n            )\n\n        # A .msg is projected onto RFC 822 for conversion, so the origin uses\n        # the message/rfc822 mimetype for both inputs (DocumentOrigin only\n        # accepts registered MIME types); the .msg filename fallback preserves\n        # the distinction when no filename is available.\n        origin = DocumentOrigin(\n            filename=self.file.name or (\"file.msg\" if self.is_msg else \"file.eml\"),\n            mimetype=\"message/rfc822\",\n            binary_hash=self.document_hash,\n        )\n        doc = DoclingDocument(name=self.file.stem or \"file\", origin=origin)\n\n        subject = (\n            self.mail.subject.strip() if isinstance(self.mail.subject, str) else \"\"\n        )\n        from_text = self._format_addresses(self.mail.from_, fallback=\"\")","sourceCodeStart":268,"sourceCodeEnd":304,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/email_backend.py#L268-L304","documentation":"EmailDocumentBackend.convert() raises RuntimeError when is_valid() is false or self.mail is None, meaning __init__ never successfully parsed a message (init failures are raised at construction, so reaching convert() in this state usually means the backend was built through a path that swallowed the init error). The guard prevents attribute errors on None later in conversion.","triggerScenarios":"Calling convert() after init partially failed — self.mail stayed None — or on a backend instance kept from a failed conversion attempt; also reachable when parse_from_bytes returned None.","commonSituations":"Frameworks that catch DocumentLoadError from construction but still call convert() on the half-built backend; retry loops reusing the same backend object.","solutions":["Treat construction failure as fatal: do not call convert() on a backend whose __init__ raised","Check backend.is_valid() and backend.mail is not None before convert()","Create a fresh backend instance per conversion attempt"],"exampleFix":"# before\ndoc = backend.convert()\n\n# after\nif not backend.is_valid() or backend.mail is None:\n    raise ValueError('email backend did not parse a message; re-check the input')\ndoc = backend.convert()","handlingStrategy":"validation","validationCode":"if not backend.is_valid() or backend.mail is None:\n    raise ValueError('email backend not initialized; do not call convert()')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never call convert() on a backend whose __init__ raised","Create a fresh backend per conversion attempt"],"tags":["email","state-machine","lifecycle"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}