{"record":{"id":"9b30c7bd8e303437","repo":"docling-project/docling","slug":"cannot-convert-md-with-self-document-hash-becaus","errorCode":null,"errorMessage":"Cannot convert md with {self.document_hash} because the backend failed to init.","messagePattern":"Cannot convert md with (.+?) because the backend failed to init\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/backend/md_backend.py","lineNumber":852,"sourceCode":"                    source_uri=md_options.source_uri,\n                    infer_furniture=False,\n                    add_title=False,\n                )\n                in_doc = InputDocument(\n                    path_or_stream=stream,\n                    format=InputFormat.HTML,\n                    backend=html_backend_cls,\n                    filename=self.file.name,\n                    backend_options=html_options,\n                )\n                html_backend_obj = html_backend_cls(\n                    in_doc=in_doc,\n                    path_or_stream=stream,\n                    options=html_options,\n                )\n                doc = html_backend_obj.convert()\n        else:\n            raise RuntimeError(\n                f\"Cannot convert md with {self.document_hash} because the backend failed to init.\"\n            )\n        return doc\n","sourceCodeStart":834,"sourceCodeEnd":856,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/md_backend.py#L834-L856","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check backend.is_valid() before calling convert() and skip/queue-for-retry invalid documents.","Fix the underlying load failure (encoding/IO problem in the .md file) so init sets valid=True.","Catch RuntimeError (or check is_valid) in batch pipelines and log the source path instead of letting it abort the batch."],"exampleFix":"# before\nbackend = MarkdownDocumentBackend(in_doc, path)\ndoc = backend.convert()  # RuntimeError if init failed\n\n# after\nbackend = MarkdownDocumentBackend(in_doc, path)\nif not backend.is_valid():\n    logger.error('skipping %s: backend init failed', path)\n    return None\ndoc = backend.convert()","handlingStrategy":"validation","validationCode":"# via DocumentConverter the load error surfaces first; for manual backend use:\nbackend = MarkdownDocumentBackend(in_doc, path)\nif not backend.is_valid():\n    skip(path)  # do not call convert()","typeGuard":"def backend_ready(backend) -> bool:\n    return bool(getattr(backend, 'valid', False)) or backend.is_valid()","tryCatchPattern":"if not backend.is_valid():\n    log.warning('skipping %s: MD backend not initialized', path)\n    return None\ntry:\n    doc = backend.convert()\nexcept RuntimeError:\n    log.error('conversion attempted on invalid backend for %s', path)\n    return None","preventionTips":["Treat a failed backend init as terminal for that document; never proceed to convert().","Check is_valid() as a standing step in custom backend pipelines.","Let the init DocumentLoadError propagate instead of swallowing it."],"tags":["markdown","state-check","guard"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}