docling-project/docling · error · DocumentLoadError

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

EBCDICBackend.convert() raises DocumentLoadError when is_valid() is false, i.e. self.content is empty because __init__ failed to read any bytes from the document (the init failure itself is reported separately). This guard prevents convert() from producing an empty, misleading document from a backend that never loaded data.

Source

Thrown at docling/backend/ebcdic_backend.py:272

    @override
    def is_valid(self) -> bool:
        return bool(self.content)

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

    @classmethod
    @override
    def supported_formats(cls) -> set[InputFormat]:
        return {InputFormat.EBCDIC}

    @override
    def convert(self) -> DoclingDocument:
        """Parse the EBCDIC data into one table per record schema."""
        if not self.is_valid():
            raise DocumentLoadError(
                f"Cannot convert doc with {self.document_hash} because the "
                "backend failed to init."
            )

        origin = DocumentOrigin(
            filename=self.file.name or "file.ebc",
            mimetype=_MIME_TYPE,
            binary_hash=self.document_hash,
        )
        doc = DoclingDocument(name=self.file.stem or "file", origin=origin)
        if self.layout.description:
            doc.add_text(label=DocItemLabel.TEXT, text=self.layout.description)

        decoder = _FieldDecoder(
            self.options.encoding, self.options.strip_control_characters
        )
        rows = _RecordParser(self.layout, decoder).parse(
            self.content, self.options.max_records

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Check backend.is_valid() (or document validity) before calling convert()
2. Verify the source file is non-empty before starting conversion
3. For streams, seek(0) or pass a fresh BytesIO per conversion

Example fix

# before
doc = backend.convert()

# after
if not backend.is_valid():
    raise ValueError('EBCDIC source is empty; check the input file/stream')
doc = backend.convert()

if not backend.is_valid():
    raise ValueError('EBCDIC backend has no content; input file/stream is empty')

When it happens

Trigger: Calling convert() on an EBCDIC backend whose content is empty: a zero-byte file, a stream already consumed, or a read failure during __init__ that was swallowed upstream.

Common situations: Reusing a BytesIO that a previous conversion already read to EOF; uploading empty files through a service that maps init errors to warnings and still calls convert(); race conditions where the file is truncated/deleted between init and convert.

Related errors

• Unknown EBCDIC codec {encoding!r}.
• Cannot decode field {field.name!r} of type {field.type.value
• No record layout matches record type {record_type!r}.
• Record length {length} is shorter than the {layout.prefix_si
• Input ends inside {name!r}: {end - offset} of {size} bytes l

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