docling-project/docling · error · DocumentLoadError

Could not initialize MD backend for file with hash {self.doc

Error message

Could not initialize MD backend for file with hash {self.document_hash}.

What it means

DocumentLoadError raised by the Markdown backend's __init__ (via init loading of the file) when the .md file could not be read or preprocessed. The backend opens the file with UTF-8 encoding, shortens pathological underscore/dash sequences, and any exception in that path (encoding error, missing file, permission problem) is wrapped into this error with the document's hash. It signals that Markdown ingestion never got past file loading, not a conversion-logic failure.

Source

Thrown at docling/backend/md_backend.py:270

                # very long sequences of underscores will lead to unnecessary long processing times.
                # In any proper Markdown files, underscores have to be escaped,
                # otherwise they represent emphasis (bold or italic)
                self.markdown = self._shorten_underscore_sequences(text_stream)
                self.markdown = self._shorten_leading_dash_sequences(self.markdown)
            if isinstance(self.path_or_stream, Path):
                with open(self.path_or_stream, encoding="utf-8") as f:
                    md_content = f.read()
                    # remove invalid sequences
                    # very long sequences of underscores will lead to unnecessary long processing times.
                    # In any proper Markdown files, underscores have to be escaped,
                    # otherwise they represent emphasis (bold or italic)
                    self.markdown = self._shorten_underscore_sequences(md_content)
                    self.markdown = self._shorten_leading_dash_sequences(self.markdown)
            self.valid = True

            _log.debug(self.markdown)
        except Exception as e:
            raise DocumentLoadError(
                f"Could not initialize MD backend for file with hash {self.document_hash}."
            ) from e
        return

    def _close_table(self, doc: DoclingDocument):
        self.in_pipeless_table = False
        if self.in_table:
            _log.debug("=== TABLE START ===")
            for md_table_row in self.md_table_buffer:
                _log.debug(md_table_row)
            _log.debug("=== TABLE END ===")
            tcells: list[TableCell] = []
            result_table = []
            for n, md_table_row in enumerate(self.md_table_buffer):
                data = []
                if n == 0:
                    header = MarkdownDocumentBackend._split_table_row(md_table_row)
                    for value in header:

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Verify the file exists and is readable before conversion: `Path(p).read_text(encoding='utf-8')` in a pre-check.
2. Re-encode the input to UTF-8 (`iconv -f WINDOWS-1252 -t UTF-8 in.md -o out.md`) since the backend hard-codes encoding="utf-8".
3. If passing a stream, ensure it is seekable and rewound (stream.seek(0)) before handing it to the converter.
4. Inspect the chained cause (`e.__cause__`) from the caught DocumentLoadError to identify the real IO/Unicode error.

Example fix

// before
with open('legacy.md', 'rb') as f:
    doc = converter.convert(f)  # UnicodeDecodeError -> DocumentLoadError

// after
raw = Path('legacy.md').read_bytes()
text = raw.decode('utf-8', errors='replace')
import io
from docling.document_converter import DocumentConverter
from docling.datamodel.base_models import DocumentStream
from pydantic import AnyUrl
doc = converter.convert(DocumentStream(name='legacy.md', stream=io.BytesIO(text.encode('utf-8'))))

from pathlib import Path

def md_is_loadable(path: str) -> bool:
    p = Path(path)
    try:
        p.read_text(encoding='utf-8')
        return True
    except (OSError, UnicodeDecodeError):
        return False

from docling.core.exceptions import DocumentLoadError
try:
    result = converter.convert(md_path)
except DocumentLoadError as e:
    log.error('md load failed (%s): %s', md_path, e.__cause__)

When it happens

Trigger: Calling DocumentConverter.convert() (or the MD backend directly) on a file whose bytes are not valid UTF-8, a file deleted/moved between discovery and load, an unreadable file (permissions), or a stream already consumed. The `except Exception` in MarkdownDocumentBackend init catches it and re-raises as DocumentLoadError.

Common situations: Windows-1252/latin-1 encoded Markdown files, files with a BOM or binary garbage, pipelines that pass a BytesIO that was already read to EOF, or race conditions where a temp file is cleaned up before conversion starts.

Related errors

• CsvDocumentBackend could not load document with hash {self.d
• Could not initialize the EBCDIC backend for file with hash {
• Could not initialize the WebVTT backend for file with hash {
• Could not initialize USPTO backend for file with hash {self.
• docling-parse could not load document {self.document_hash}:

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