{"record":{"id":"23d262410f350e83","repo":"docling-project/docling","slug":"cannot-convert-doc-with-self-document-hash-becau","errorCode":null,"errorMessage":"Cannot convert doc with {self.document_hash} because the backend failed to init.","messagePattern":"Cannot convert doc with (.+?) because the backend failed to init\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/backend/csv_backend.py","lineNumber":131,"sourceCode":"                # Convert each cell to TableCell\n                for row_idx, row in enumerate(self.csv_data):\n                    for col_idx, cell_value in enumerate(row):\n                        cell = TableCell(\n                            text=str(cell_value),\n                            row_span=1,  # CSV doesn't support merged cells\n                            col_span=1,\n                            start_row_offset_idx=row_idx,\n                            end_row_offset_idx=row_idx + 1,\n                            start_col_offset_idx=col_idx,\n                            end_col_offset_idx=col_idx + 1,\n                            column_header=row_idx == 0,  # First row as header\n                            row_header=False,\n                        )\n                        table_data.table_cells.append(cell)\n\n                doc.add_table(data=table_data)\n        else:\n            raise RuntimeError(\n                f\"Cannot convert doc with {self.document_hash} because the backend failed to init.\"\n            )\n\n        return doc\n","sourceCodeStart":113,"sourceCodeEnd":136,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/csv_backend.py#L113-L136","documentation":"CsvDocumentBackend.convert() raises this RuntimeError in its final else branch when the backend considers itself uninitialized (self.valid False / content not loaded) at conversion time. Because __init__ raises DocumentLoadError on any read/decode failure, reaching this guard usually means convert() was called on a backend that was never successfully constructed, or on one constructed with an input that was neither BytesIO nor Path (which sets valid=True but never sets content). It marks a state-machine misuse rather than a data problem.","triggerScenarios":"Calling convert() on a CsvDocumentBackend instance whose construction failed (catching the DocumentLoadError and continuing with the half-built object); or constructing the backend with a type that is neither BytesIO nor Path (e.g. a str), then converting.","commonSituations":"Batch code that wraps backend construction in try/except DocumentLoadError but keeps and converts the object anyway; passing str paths instead of pathlib.Path; calling convert() after unload().","solutions":["Do not convert a backend whose __init__ raised — treat a DocumentLoadError from the constructor as fatal for that document and skip it.","Always pass pathlib.Path or io.BytesIO; convert str with Path('file.csv') before constructing.","Check backend.is_valid() before convert() when using the backend directly.","Prefer the DocumentConverter API, which gates conversion on validity for you."],"exampleFix":"# before\ntry:\n    be = CsvDocumentBackend(inp, path_or_stream)\nexcept DocumentLoadError:\n    pass\ndoc = be.convert()  # raises: backend failed to init\n\n# after\ntry:\n    be = CsvDocumentBackend(inp, Path('data.csv'))\nexcept DocumentLoadError:\n    skip_file()  # do not reuse the object\nelse:\n    doc = be.convert() if be.is_valid() else skip_file()","handlingStrategy":"validation","validationCode":"# Never convert a backend whose constructor raised.\ntry:\n    backend = CsvDocumentBackend(inp, Path(\"data.csv\"))\nexcept DocumentLoadError:\n    backend = None\nif backend is None or not backend.is_valid():\n    skip(\"data.csv\")\nelse:\n    doc = backend.convert()","typeGuard":null,"tryCatchPattern":"try:\n    doc = backend.convert()\nexcept RuntimeError as e:\n    if \"backend failed to init\" in str(e):\n        skip(path)  # state misuse: do not retry the same object\n    else:\n        raise","preventionTips":["Treat constructor DocumentLoadError as fatal for that document; never reuse the object.","Pass pathlib.Path or io.BytesIO so the backend actually loads content.","Let DocumentConverter manage validity gating instead of driving backends manually."],"tags":["csv","state-misuse","convert","validation"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}