docling-project/docling · error · DocumentLoadError

Could not initialize the EBCDIC backend for file with hash {

Error message

Could not initialize the EBCDIC backend for file with hash {self.document_hash}.

What it means

EbcdicDocumentBackend.__init__ raises this DocumentLoadError when reading the raw bytes from the input fails: it calls BytesIO.getvalue() or Path.read_bytes(), catching OSError and ValueError. OSError covers missing/unreadable files; ValueError covers I/O on closed streams (a closed BytesIO raises ValueError). Note the backend deliberately reads from the constructor argument, not self.path_or_stream, because unload() clears the latter — so this error is purely about obtaining the bytes.

Source

Thrown at docling/backend/ebcdic_backend.py:232

        in_doc: InputDocument,
        path_or_stream: Union[BytesIO, Path],
        options: Union[EbcdicBackendOptions, None] = None,
    ) -> None:
        if options is None:
            options = EbcdicBackendOptions()
        super().__init__(in_doc, path_or_stream, options)

        self.layout = self._resolve_layout()
        try:
            # Read from the argument rather than self.path_or_stream, which
            # unload() clears to None.
            self.content = (
                path_or_stream.getvalue()
                if isinstance(path_or_stream, BytesIO)
                else path_or_stream.read_bytes()
            )
        except (OSError, ValueError) as exc:
            raise DocumentLoadError(
                "Could not initialize the EBCDIC backend for file with hash "
                f"{self.document_hash}."
            ) from exc

    def _resolve_layout(self) -> EbcdicLayout:
        if self.options.layout is not None:
            return self.options.layout
        if self.options.layout_file is None:
            raise DocumentLoadError(
                "The EBCDIC backend needs a layout: set either "
                "EbcdicBackendOptions.layout or EbcdicBackendOptions.layout_file."
            )
        try:
            return EbcdicLayout.model_validate_json(
                self.options.layout_file.read_bytes()
            )
        except (OSError, ValueError) as exc:
            raise DocumentLoadError(

View on GitHub (pinned to 61d76f1ff3)

Solutions

Check the file exists and is readable: Path(p).is_file() and os.access(p, os.R_OK).
Do not close the BytesIO before handing it to the converter; if you must manage lifetime, pass fresh BytesIO(data).
Inspect e.__cause__: OSError -> path/permission issue; ValueError -> closed stream.
For network mounts, verify availability (mount status) before the conversion job starts.

Example fix

# before
buf = BytesIO(data)
process(buf)
buf.close()
conv.convert(buf, pipeline_options=opts)  # ValueError: closed file -> error 19

# after
conv.convert(BytesIO(data), pipeline_options=opts)  # fresh open stream

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
from io import BytesIO
import os

def readable_source(src: Path | BytesIO) -> bool:
    if isinstance(src, Path):
        return src.is_file() and os.access(src, os.R_OK)
    return isinstance(src, BytesIO) and not src.closed  # closed streams raise ValueError

Type guard

from io import BytesIO
from pathlib import Path

def is_acceptable_source(src) -> bool:
    return (isinstance(src, Path) and src.is_file()) or (isinstance(src, BytesIO) and not src.closed)

Try / catch

from docling.exceptions import DocumentLoadError
try:
    conv.convert(src, pipeline_options=opts)
except DocumentLoadError as e:
    if isinstance(e.__cause__, ValueError):
        conv.convert(BytesIO(data), pipeline_options=opts)  # fresh, open stream
    elif isinstance(e.__cause__, OSError):
        fix_permissions_or_skip(src)

Prevention

Do not close BytesIO streams before conversion; hand over ownership.
Check Path.is_file() and read permission before enqueuing files.
In batch jobs, verify mounts are alive before processing queued paths.

When it happens

Trigger: Passing a Path that does not exist or has no read permission; passing a BytesIO that was closed before conversion (buf.close() then convert); reading from a broken network mount. It fires before any EBCDIC decoding — a separate error covers a missing layout (EbcdicBackendOptions.layout / layout_file).

Common situations: Streams closed by cleanup code (with-block exited, temp-file buffers closed) before docling reads them; paths from config/queues pointing at deleted files; containerized runs hitting a permissions change on mounted volumes.

Related errors

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