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

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.

Source

Thrown at docling/backend/msexcel_backend.py:505

        Raises:
            RuntimeError: Unable to run the conversion since the backend object failed to
            initialize.

        Returns:
            The DoclingDocument object representing the Excel workbook.
        """
        origin = DocumentOrigin(
            filename=self.file.name or "file.xlsx",
            mimetype=FormatToMimeType[self.input_format][0],
            binary_hash=self.document_hash,
        )

        doc = DoclingDocument(name=self.file.stem or "file.xlsx", origin=origin)

        if self.is_valid():
            doc = self._convert_workbook(doc)
        else:
            raise RuntimeError(
                f"Cannot convert doc with {self.document_hash} because the backend failed to init."
            )

        return doc

    def _convert_workbook(self, doc: DoclingDocument) -> DoclingDocument:
        """Parse the Excel workbook and attach its structure to a DoclingDocument.

        Args:
            doc: A DoclingDocument object.

        Returns:
            A DoclingDocument object with the parsed items.
        """

        if self.workbook is not None:
            sheet_names_filter: list[str] | None = (
                self.options.sheet_names

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Always check backend.is_valid() before convert() when driving backends manually.
2. Fix the underlying load failure (corrupt/unsupported workbook — see the Excel DocumentLoadError).
3. In batch jobs, catch this RuntimeError, log the file, and continue with the next document.

Example fix

# before
backend = MsExcelDocumentBackend(in_doc, path)
doc = backend.convert()  # RuntimeError

# after
backend = MsExcelDocumentBackend(in_doc, path)
if not backend.is_valid():
    logger.error('invalid workbook: %s', path)
    return None
doc = backend.convert()

backend = MsExcelDocumentBackend(in_doc, path)
if not backend.is_valid():
    skip(path)  # never call convert() on an invalid backend

def backend_ready(backend) -> bool:
    return backend.is_valid()

if not backend.is_valid():
    log.warning('skipping %s: Excel backend not initialized', path)
    return None
try:
    doc = backend.convert()
except RuntimeError:
    log.error('convert() on invalid Excel backend for %s', path)
    return None

When it happens

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

Common situations: 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.

Related errors

• Cannot convert md with {self.document_hash} because the back
• The 'openpyxl' package is required to process Excel files. I
• MsExcelDocumentBackend could not load document with hash {se
• Cannot convert doc with {self.document_hash} because the bac
• Cannot convert doc with {self.document_hash} because the bac

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