docling-project/docling · error · RuntimeError

Cannot convert md with {self.document_hash} because the back

Error message

Cannot convert md with {self.document_hash} because the backend failed to init.

What it means

RuntimeError raised by MarkdownDocumentBackend.convert() when conversion is attempted but self.valid is False, i.e. the backend's init/load step failed earlier. It is the 'you converted after a failed load' guard: the constructor already raised or marked the backend invalid, and convert() refuses to proceed. The root cause is whatever made init fail (see the MD DocumentLoadError) and __cause__ will not carry it — you must handle the init error.

Source

Thrown at docling/backend/md_backend.py:852

                    source_uri=md_options.source_uri,
                    infer_furniture=False,
                    add_title=False,
                )
                in_doc = InputDocument(
                    path_or_stream=stream,
                    format=InputFormat.HTML,
                    backend=html_backend_cls,
                    filename=self.file.name,
                    backend_options=html_options,
                )
                html_backend_obj = html_backend_cls(
                    in_doc=in_doc,
                    path_or_stream=stream,
                    options=html_options,
                )
                doc = html_backend_obj.convert()
        else:
            raise RuntimeError(
                f"Cannot convert md with {self.document_hash} because the backend failed to init."
            )
        return doc

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Check backend.is_valid() before calling convert() and skip/queue-for-retry invalid documents.
2. Fix the underlying load failure (encoding/IO problem in the .md file) so init sets valid=True.
3. Catch RuntimeError (or check is_valid) in batch pipelines and log the source path instead of letting it abort the batch.

Example fix

# before
backend = MarkdownDocumentBackend(in_doc, path)
doc = backend.convert()  # RuntimeError if init failed

# after
backend = MarkdownDocumentBackend(in_doc, path)
if not backend.is_valid():
    logger.error('skipping %s: backend init failed', path)
    return None
doc = backend.convert()

# via DocumentConverter the load error surfaces first; for manual backend use:
backend = MarkdownDocumentBackend(in_doc, path)
if not backend.is_valid():
    skip(path)  # do not call convert()

def backend_ready(backend) -> bool:
    return bool(getattr(backend, 'valid', False)) or backend.is_valid()

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

When it happens

Trigger: Instantiating MarkdownDocumentBackend on a bad file while swallowing the init exception, then calling convert(); or calling convert() after DocumentConverter returned a backend whose is_valid() is False (e.g. a load error was caught and logged by calling code).

Common situations: Custom pipelines that build backends manually and skip checking backend.is_valid() before convert(); error-handling code that catches DocumentLoadError from init and continues to the conversion step anyway.

Related errors

• Cannot convert doc with {self.document_hash} because the bac
• The 'marko' package is required to process Markdown files. I
• Could not initialize MD backend for file with hash {self.doc
• An internal error has occurred during Markdown conversion.
• 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/9b30c7bd8e303437. Report an issue: GitHub.