{"record":{"id":"3c17f5e807775c07","repo":"docling-project/docling","slug":"csvdocumentbackend-could-not-load-document-with-ha","errorCode":null,"errorMessage":"CsvDocumentBackend could not load document with hash {self.document_hash}","messagePattern":"CsvDocumentBackend could not load document with hash (.+?)","errorType":"exception","errorClass":"DocumentLoadError","httpStatus":null,"severity":"error","filePath":"docling/backend/csv_backend.py","lineNumber":32,"sourceCode":"\n_log = logging.getLogger(__name__)\n\n\nclass CsvDocumentBackend(DeclarativeDocumentBackend):\n    content: StringIO\n\n    def __init__(self, in_doc: \"InputDocument\", path_or_stream: Union[BytesIO, Path]):\n        super().__init__(in_doc, path_or_stream)\n\n        # Load content\n        try:\n            if isinstance(self.path_or_stream, BytesIO):\n                self.content = StringIO(self.path_or_stream.getvalue().decode(\"utf-8\"))\n            elif isinstance(self.path_or_stream, Path):\n                self.content = StringIO(self.path_or_stream.read_text(\"utf-8\"))\n            self.valid = True\n        except Exception as e:\n            raise DocumentLoadError(\n                f\"CsvDocumentBackend could not load document with hash {self.document_hash}\"\n            ) from e\n        return\n\n    def is_valid(self) -> bool:\n        return self.valid\n\n    @classmethod\n    def supports_pagination(cls) -> bool:\n        return False\n\n    def unload(self):\n        if isinstance(self.path_or_stream, BytesIO):\n            self.path_or_stream.close()\n        self.path_or_stream = None\n\n    @classmethod\n    def supported_formats(cls) -> Set[InputFormat]:","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/csv_backend.py#L14-L50","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nresult = conv.convert(Path('export.csv'))  # cp1252 bytes -> raises\n\n# after\nraw = Path('export.csv').read_bytes()\ntext = raw.decode('cp1252')  # match the real encoding\nfrom io import BytesIO\nresult = conv.convert(BytesIO(text.encode('utf-8')))","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef as_utf8_csv_source(path: Path):\n    raw = path.read_bytes()\n    try:\n        text = raw.decode(\"utf-8\")\n    except UnicodeDecodeError:\n        text = raw.decode(\"cp1252\")  # or detect encoding before falling back\n    from io import BytesIO\n    return BytesIO(text.encode(\"utf-8\"))","typeGuard":null,"tryCatchPattern":"from docling.exceptions import DocumentLoadError\ntry:\n    result = conv.convert(src)\nexcept DocumentLoadError as e:\n    if isinstance(e.__cause__, UnicodeDecodeError):\n        result = conv.convert(as_utf8_csv_source(src))  # retry re-encoded\n    else:\n        raise","preventionTips":["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."],"tags":["csv","encoding","document-load","utf-8"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}