docling-project/docling · error · DocumentLoadError

The EBCDIC backend needs a layout: set either EbcdicBackendO

Error message

The EBCDIC backend needs a layout: set either EbcdicBackendOptions.layout or EbcdicBackendOptions.layout_file.

What it means

The EBCDIC backend requires a record layout describing fixed-width fields before it can parse mainframe data. _resolve_layout() raises DocumentLoadError when EbcdicBackendOptions.layout is None and layout_file is also None. Without a layout the backend cannot map EBCDIC byte columns to table cells, so it refuses to load rather than guessing.

Source

Thrown at docling/backend/ebcdic_backend.py:241

        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(
                f"Could not read the EBCDIC layout {self.options.layout_file}."
            ) from exc

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

    @classmethod
    @override

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Set EbcdicBackendOptions.layout to an EbcdicLayout instance built in code
2. Or set EbcdicBackendOptions.layout_file to a Path of JSON matching the EbcdicLayout schema (validated with EbcdicLayout.model_validate_json)
3. If loading from a file, verify the path exists and the JSON validates before passing it to the backend

Example fix

# before
opts = EbcdicBackendOptions()
doc = DocumentConverter(format_options={InputFormat.EBCDIC: PdfFormatOptions(backend_opts=opts)}).convert(src)

# after
opts = EbcdicBackendOptions(layout=EbcdicLayout.model_validate_json(Path('layout.json').read_text()))
# or: opts = EbcdicBackendOptions(layout_file=Path('layout.json'))

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfFormatOptions
from docling.backend.ebcdic_backend import EbcdicBackendOptions

opts = EbcdicBackendOptions()
assert opts.layout is not None or opts.layout_file is not None, (
    'EBCDIC conversion requires EbcdicBackendOptions.layout or .layout_file'
)

try:
    result = converter.convert(src)
except DocumentLoadError as exc:
    if 'needs a layout' in str(exc):
        raise ConfigError('EBCDIC layout not configured') from exc
    raise

When it happens

Trigger: Creating an EBCDIC backend / converting a file with InputFormat.EBCDIC while EbcdicBackendOptions() is left at defaults, or when options are built but neither the `layout` (in-memory EbcdicLayout) nor `layout_file` (Path to JSON) attribute is assigned.

Common situations: Teams adopting the EBCDIC backend copy example code that omits layout setup; CI pipelines that pass a generic EbcdicBackendOptions() for all formats; refactors that drop the layout_file argument.

Related errors

• Unknown EBCDIC codec {encoding!r}.
• Cannot decode field {field.name!r} of type {field.type.value
• Could not read the EBCDIC layout {self.options.layout_file}.
• record_type_field is required for a layout with several reco
• No record layout matches record type {record_type!r}.

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