docling-project/docling · error · RuntimeError

Cannot convert doc with {self.document_hash} because the bac

Error message

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

What it means

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.

Source

Thrown at docling/backend/csv_backend.py:131

                # Convert each cell to TableCell
                for row_idx, row in enumerate(self.csv_data):
                    for col_idx, cell_value in enumerate(row):
                        cell = TableCell(
                            text=str(cell_value),
                            row_span=1,  # CSV doesn't support merged cells
                            col_span=1,
                            start_row_offset_idx=row_idx,
                            end_row_offset_idx=row_idx + 1,
                            start_col_offset_idx=col_idx,
                            end_col_offset_idx=col_idx + 1,
                            column_header=row_idx == 0,  # First row as header
                            row_header=False,
                        )
                        table_data.table_cells.append(cell)

                doc.add_table(data=table_data)
        else:
            raise RuntimeError(
                f"Cannot convert doc with {self.document_hash} because the backend failed to init."
            )

        return doc

View on GitHub (pinned to 61d76f1ff3)

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.

Example fix

# before
try:
    be = CsvDocumentBackend(inp, path_or_stream)
except DocumentLoadError:
    pass
doc = be.convert()  # raises: backend failed to init

# after
try:
    be = CsvDocumentBackend(inp, Path('data.csv'))
except DocumentLoadError:
    skip_file()  # do not reuse the object
else:
    doc = be.convert() if be.is_valid() else skip_file()

Defensive patterns

Strategy: validation

Validate before calling

# Never convert a backend whose constructor raised.
try:
    backend = CsvDocumentBackend(inp, Path("data.csv"))
except DocumentLoadError:
    backend = None
if backend is None or not backend.is_valid():
    skip("data.csv")
else:
    doc = backend.convert()

Try / catch

try:
    doc = backend.convert()
except RuntimeError as e:
    if "backend failed to init" in str(e):
        skip(path)  # state misuse: do not retry the same object
    else:
        raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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().

Related errors

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