docling-project/docling · error · DocumentLoadError

The EBCDIC backend needs a layout: set either…

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.

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'))
Defensive patterns

Strategy: validation

Validate before calling

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 / catch

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

Prevention

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

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

Appendix: 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)