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

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.

Source

Thrown at docling/backend/email_backend.py:286

        """Return one display label per attachment (name, optional content type).

        Only attachment metadata is surfaced; the encoded payload is never
        included, matching how ``.eml`` attachment content is excluded.
        """
        assert self.mail is not None

        labels: list[str] = []
        for index, attachment in enumerate(self.mail.attachments or []):
            filename = (attachment.get("filename") or "").strip()
            if not filename:
                filename = f"attachment-{index + 1}"
            content_type = (attachment.get("mail_content_type") or "").strip()
            labels.append(f"{filename} ({content_type})" if content_type else filename)
        return labels

    def convert(self) -> DoclingDocument:
        if not self.is_valid() or self.mail is None:
            raise RuntimeError(
                f"Cannot convert doc with {self.document_hash} because the backend failed to init."
            )

        # A .msg is projected onto RFC 822 for conversion, so the origin uses
        # the message/rfc822 mimetype for both inputs (DocumentOrigin only
        # accepts registered MIME types); the .msg filename fallback preserves
        # the distinction when no filename is available.
        origin = DocumentOrigin(
            filename=self.file.name or ("file.msg" if self.is_msg else "file.eml"),
            mimetype="message/rfc822",
            binary_hash=self.document_hash,
        )
        doc = DoclingDocument(name=self.file.stem or "file", origin=origin)

        subject = (
            self.mail.subject.strip() if isinstance(self.mail.subject, str) else ""
        )
        from_text = self._format_addresses(self.mail.from_, fallback="")

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Treat construction failure as fatal: do not call convert() on a backend whose __init__ raised
2. Check backend.is_valid() and backend.mail is not None before convert()
3. Create a fresh backend instance per conversion attempt

Example fix

# before
doc = backend.convert()

# after
if not backend.is_valid() or backend.mail is None:
    raise ValueError('email backend did not parse a message; re-check the input')
doc = backend.convert()

if not backend.is_valid() or backend.mail is None:
    raise ValueError('email backend not initialized; do not call convert()')

When it happens

Trigger: 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.

Common situations: Frameworks that catch DocumentLoadError from construction but still call convert() on the half-built backend; retry loops reusing the same backend object.

Related errors

• Cannot convert EPUB with hash {self.document_hash} because t
• Invalid HTML document.
• Cannot convert doc with {self.document_hash} because the bac
• The 'mail-parser' package is required to process email files
• Could not initialize email backend for file with hash {self.

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