docling-project/docling · error · DocumentLoadError

CsvDocumentBackend could not load document with hash {self.d

Error message

CsvDocumentBackend could not load document with hash {self.document_hash}

What it means

CsvDocumentBackend raises this DocumentLoadError when reading the CSV source fails during __init__. The backend loads the entire file into a StringIO via bytes.decode('utf-8') or Path.read_text('utf-8'); any exception in that step (classically UnicodeDecodeError for non-UTF-8 CSVs, or OSError for a bad path) is wrapped with the document hash attached and the cause chained.

Source

Thrown at docling/backend/csv_backend.py:32

_log = logging.getLogger(__name__)


class CsvDocumentBackend(DeclarativeDocumentBackend):
    content: StringIO

    def __init__(self, in_doc: "InputDocument", path_or_stream: Union[BytesIO, Path]):
        super().__init__(in_doc, path_or_stream)

        # Load content
        try:
            if isinstance(self.path_or_stream, BytesIO):
                self.content = StringIO(self.path_or_stream.getvalue().decode("utf-8"))
            elif isinstance(self.path_or_stream, Path):
                self.content = StringIO(self.path_or_stream.read_text("utf-8"))
            self.valid = True
        except Exception as e:
            raise DocumentLoadError(
                f"CsvDocumentBackend could not load document with hash {self.document_hash}"
            ) from e
        return

    def is_valid(self) -> bool:
        return self.valid

    @classmethod
    def supports_pagination(cls) -> bool:
        return False

    def unload(self):
        if isinstance(self.path_or_stream, BytesIO):
            self.path_or_stream.close()
        self.path_or_stream = None

    @classmethod
    def supported_formats(cls) -> Set[InputFormat]:

View on GitHub (pinned to 61d76f1ff3)

Solutions

Re-encode the CSV to UTF-8 before conversion: iconv -f cp1252 -t utf-8 data.csv > data.utf8.csv (use UTF-8 when saving from Excel).
If re-encoding is not possible, decode yourself with errors handled, then pass BytesIO: conv.convert(BytesIO(raw.decode('cp1252').encode('utf-8'))).
Check e.__cause__ — UnicodeDecodeError points at encoding, OSError at path/permission problems.
Ensure you pass a pathlib.Path or io.BytesIO, not a str filename or an already-closed stream.

Example fix

# before
result = conv.convert(Path('export.csv'))  # cp1252 bytes -> raises

# after
raw = Path('export.csv').read_bytes()
text = raw.decode('cp1252')  # match the real encoding
from io import BytesIO
result = conv.convert(BytesIO(text.encode('utf-8')))

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def as_utf8_csv_source(path: Path):
    raw = path.read_bytes()
    try:
        text = raw.decode("utf-8")
    except UnicodeDecodeError:
        text = raw.decode("cp1252")  # or detect encoding before falling back
    from io import BytesIO
    return BytesIO(text.encode("utf-8"))

Try / catch

from docling.exceptions import DocumentLoadError
try:
    result = conv.convert(src)
except DocumentLoadError as e:
    if isinstance(e.__cause__, UnicodeDecodeError):
        result = conv.convert(as_utf8_csv_source(src))  # retry re-encoded
    else:
        raise

Prevention

Instruct upstream producers to export CSV as UTF-8.
Normalize encoding at ingestion time so the pipeline only ever sees UTF-8 bytes.
Pass pathlib.Path or io.BytesIO, never str.

When it happens

Trigger: Converting a CSV that is not UTF-8 — cp1252/latin-1 exports from Excel on Windows, UTF-16 exports, or files with stray invalid bytes. Also a missing/unreadable Path, or a BytesIO holding non-decodable bytes. Note the except clause is broad: any exception during decode/read triggers it.

Common situations: Excel 'CSV UTF-16' exports; SAS/SPSS exports in latin-1; CSVs containing a stray byte in one field (mojibake); passing a str path or an exhausted stream (falls through both isinstance checks without error, leaving content unset — different failure mode); files on network mounts that raise OSError on read.

Related errors

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