docling-project/docling · error · DocumentLoadError

Could not read the EBCDIC layout {self.options.layout_file}.

Error message

Could not read the EBCDIC layout {self.options.layout_file}.

What it means

Raised when the EBCDIC layout file cannot be read or parsed: _resolve_layout() catches OSError (missing/unreadable file) and ValueError (JSON that does not satisfy EbcdicLayout.model_validate_json) and re-raises them as DocumentLoadError with the offending path. The original exception is chained via `from exc`, so inspect __cause__ for the real reason.

Source

Thrown at docling/backend/ebcdic_backend.py:250

            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
    def supports_pagination(cls) -> bool:
        return False

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

    @override

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Check layout_file.exists() and permissions before constructing the backend
2. Validate the JSON manually: EbcdicLayout.model_validate_json(Path(layout_file).read_bytes()) to surface the exact validation error
3. Use an absolute Path for layout_file to avoid working-directory drift
4. Regenerate the layout JSON against the current EbcdicLayout schema after upgrading Docling

Example fix

# before
opts = EbcdicBackendOptions(layout_file=Path('layout.json'))  # relative path, may not exist

# after
layout_path = Path('layout.json').resolve()
EbcdicLayout.model_validate_json(layout_path.read_bytes())  # fail early with a precise error
opts = EbcdicBackendOptions(layout_file=layout_path)

from pathlib import Path
from docling.backend.ebcdic_backend import EbcdicLayout

layout_file = Path('layout.json').resolve()
assert layout_file.is_file(), f'layout file missing: {layout_file}'
EbcdicLayout.model_validate_json(layout_file.read_bytes())  # precise schema errors early

try:
    EbcdicLayout.model_validate_json(layout_file.read_bytes())
except ValueError as exc:
    raise ConfigError(f'invalid EBCDIC layout: {exc}') from exc

When it happens

Trigger: EbcdicBackendOptions.layout_file points to a nonexistent or permission-denied path, or the file's JSON fails EbcdicLayout validation (wrong field names, missing required keys, trailing garbage).

Common situations: Relative layout paths resolved against a different working directory in Docker/CI; hand-edited layout JSON with a typo in a field name; layout file generated by an older Docling version with a changed schema.

Related errors

• Unknown EBCDIC codec {encoding!r}.
• The EBCDIC backend needs a layout: set either EbcdicBackendO
• 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

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