{"record":{"id":"f91f7ac47a02e9c7","repo":"docling-project/docling","slug":"could-not-initialize-md-backend-for-file-with-hash","errorCode":null,"errorMessage":"Could not initialize MD backend for file with hash {self.document_hash}.","messagePattern":"Could not initialize MD backend for file with hash (.+?)\\.","errorType":"exception","errorClass":"DocumentLoadError","httpStatus":null,"severity":"error","filePath":"docling/backend/md_backend.py","lineNumber":270,"sourceCode":"                # very long sequences of underscores will lead to unnecessary long processing times.\n                # In any proper Markdown files, underscores have to be escaped,\n                # otherwise they represent emphasis (bold or italic)\n                self.markdown = self._shorten_underscore_sequences(text_stream)\n                self.markdown = self._shorten_leading_dash_sequences(self.markdown)\n            if isinstance(self.path_or_stream, Path):\n                with open(self.path_or_stream, encoding=\"utf-8\") as f:\n                    md_content = f.read()\n                    # remove invalid sequences\n                    # very long sequences of underscores will lead to unnecessary long processing times.\n                    # In any proper Markdown files, underscores have to be escaped,\n                    # otherwise they represent emphasis (bold or italic)\n                    self.markdown = self._shorten_underscore_sequences(md_content)\n                    self.markdown = self._shorten_leading_dash_sequences(self.markdown)\n            self.valid = True\n\n            _log.debug(self.markdown)\n        except Exception as e:\n            raise DocumentLoadError(\n                f\"Could not initialize MD backend for file with hash {self.document_hash}.\"\n            ) from e\n        return\n\n    def _close_table(self, doc: DoclingDocument):\n        self.in_pipeless_table = False\n        if self.in_table:\n            _log.debug(\"=== TABLE START ===\")\n            for md_table_row in self.md_table_buffer:\n                _log.debug(md_table_row)\n            _log.debug(\"=== TABLE END ===\")\n            tcells: list[TableCell] = []\n            result_table = []\n            for n, md_table_row in enumerate(self.md_table_buffer):\n                data = []\n                if n == 0:\n                    header = MarkdownDocumentBackend._split_table_row(md_table_row)\n                    for value in header:","sourceCodeStart":252,"sourceCodeEnd":288,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/md_backend.py#L252-L288","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the file exists and is readable before conversion: `Path(p).read_text(encoding='utf-8')` in a pre-check.","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\".","If passing a stream, ensure it is seekable and rewound (stream.seek(0)) before handing it to the converter.","Inspect the chained cause (`e.__cause__`) from the caught DocumentLoadError to identify the real IO/Unicode error."],"exampleFix":"// before\nwith open('legacy.md', 'rb') as f:\n    doc = converter.convert(f)  # UnicodeDecodeError -> DocumentLoadError\n\n// after\nraw = Path('legacy.md').read_bytes()\ntext = raw.decode('utf-8', errors='replace')\nimport io\nfrom docling.document_converter import DocumentConverter\nfrom docling.datamodel.base_models import DocumentStream\nfrom pydantic import AnyUrl\ndoc = converter.convert(DocumentStream(name='legacy.md', stream=io.BytesIO(text.encode('utf-8'))))","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef md_is_loadable(path: str) -> bool:\n    p = Path(path)\n    try:\n        p.read_text(encoding='utf-8')\n        return True\n    except (OSError, UnicodeDecodeError):\n        return False","typeGuard":null,"tryCatchPattern":"from docling.core.exceptions import DocumentLoadError\ntry:\n    result = converter.convert(md_path)\nexcept DocumentLoadError as e:\n    log.error('md load failed (%s): %s', md_path, e.__cause__)","preventionTips":["Normalize all Markdown input to UTF-8 before ingestion.","Rewind streams (seek(0)) before passing them to the converter.","Check file readability right before conversion in async pipelines to avoid TOCTOU gaps."],"tags":["markdown","encoding","io","document-load"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}