{"record":{"id":"05ef813b8f0c96ec","repo":"docling-project/docling","slug":"could-not-initialize-email-backend-for-file-with-h","errorCode":null,"errorMessage":"Could not initialize email backend for file with hash {self.document_hash}.","messagePattern":"Could not initialize email backend for file with hash (.+?)\\.","errorType":"exception","errorClass":"DocumentLoadError","httpStatus":null,"severity":"error","filePath":"docling/backend/email_backend.py","lineNumber":102,"sourceCode":"        super().__init__(in_doc, path_or_stream, options)\n\n        self.options: EmailBackendOptions = options\n        self.valid = False\n        self.is_msg = False\n        self.mail: mailparser.MailParser | None = None\n\n        try:\n            raw = self._read_bytes()\n            self.is_msg = raw.startswith(_MSG_MAGIC)\n            if self.is_msg:\n                raw = self._msg_to_rfc822_bytes(raw)\n            self.mail = mailparser.parse_from_bytes(raw)\n\n            self.valid = self.mail is not None\n        except ImportError:\n            raise\n        except Exception as exc:\n            raise DocumentLoadError(\n                f\"Could not initialize email backend for file with hash {self.document_hash}.\"\n            ) from exc\n\n    def _read_bytes(self) -> bytes:\n        if isinstance(self.path_or_stream, BytesIO):\n            return self.path_or_stream.getvalue()\n        if isinstance(self.path_or_stream, Path):\n            return self.path_or_stream.read_bytes()\n        raise TypeError(f\"Unsupported input type: {type(self.path_or_stream)}\")\n\n    @staticmethod\n    def _header_safe(value: str) -> str:\n        # Email header values must be single-line; collapse CR/LF to spaces so a\n        # crafted .msg cannot inject headers and EmailMessage does not reject it.\n        return value.replace(\"\\r\", \" \").replace(\"\\n\", \" \").strip()\n\n    @staticmethod\n    def _msg_to_rfc822_bytes(data: bytes) -> bytes:","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/email_backend.py#L84-L120","documentation":"EmailDocumentBackend.__init__ wraps any non-ImportError exception raised while reading the input and parsing it with mailparser.parse_from_bytes() into DocumentLoadError. Common causes are malformed RFC 822 content, undecodable headers/bodies, or unreadable files; the true cause is chained as __cause__.","triggerScenarios":"Passing a corrupt or truncated .eml, a file that is not an email at all (e.g. a renamed .txt), or input that makes mailparser.parse_from_bytes raise. Note _read_bytes TypeError is also caught here since it inherits Exception.","commonSituations":"Bulk-ingesting mixed mail archives where some files are broken; files with legacy non-UTF8 encodings; disk/permission errors on the email path.","solutions":["Inspect exc.__cause__ on the DocumentLoadError to find the underlying mailparser error","Verify the file is a real email (starts with headers like 'From:'/'Received:') before conversion","Open the .eml in a mail client or Python email.parser to confirm it parses standalone","Quarantine unparseable files and continue batch processing instead of aborting the run"],"exampleFix":"# before\nres = converter.convert(email_path)  # crashes the batch on one bad file\n\n# after\ntry:\n    res = converter.convert(email_path)\nexcept DocumentLoadError as exc:\n    log.warning('skipping %s: %s', email_path, exc.__cause__ or exc)\n    continue","handlingStrategy":"try-catch","validationCode":"raw = Path(email_path).read_bytes()\nhead = raw[:512].lstrip().lower()\nif not (head.startswith(b'from ') or head.startswith(b'received:') or head.startswith(b'return-path')):\n    raise ValueError(f'{email_path} does not look like an RFC 822 message')","typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(email_path)\nexcept DocumentLoadError as exc:\n    log.warning('unparseable email %s: %s', email_path, exc.__cause__ or exc)\n    quarantine(email_path)","preventionTips":["Sniff for RFC 822 headers before conversion","Quarantine failures and keep batch runs alive instead of aborting"],"tags":["email","parsing","corrupt-input"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}