{"record":{"id":"286ae5e811bc1281","repo":"docling-project/docling","slug":"could-not-read-the-ebcdic-layout-self-options-lay","errorCode":null,"errorMessage":"Could not read the EBCDIC layout {self.options.layout_file}.","messagePattern":"Could not read the EBCDIC layout (.+?)\\.","errorType":"exception","errorClass":"DocumentLoadError","httpStatus":null,"severity":"error","filePath":"docling/backend/ebcdic_backend.py","lineNumber":250,"sourceCode":"            raise DocumentLoadError(\n                \"Could not initialize the EBCDIC backend for file with hash \"\n                f\"{self.document_hash}.\"\n            ) from exc\n\n    def _resolve_layout(self) -> EbcdicLayout:\n        if self.options.layout is not None:\n            return self.options.layout\n        if self.options.layout_file is None:\n            raise DocumentLoadError(\n                \"The EBCDIC backend needs a layout: set either \"\n                \"EbcdicBackendOptions.layout or EbcdicBackendOptions.layout_file.\"\n            )\n        try:\n            return EbcdicLayout.model_validate_json(\n                self.options.layout_file.read_bytes()\n            )\n        except (OSError, ValueError) as exc:\n            raise DocumentLoadError(\n                f\"Could not read the EBCDIC layout {self.options.layout_file}.\"\n            ) from exc\n\n    @override\n    def is_valid(self) -> bool:\n        return bool(self.content)\n\n    @classmethod\n    @override\n    def supports_pagination(cls) -> bool:\n        return False\n\n    @classmethod\n    @override\n    def supported_formats(cls) -> set[InputFormat]:\n        return {InputFormat.EBCDIC}\n\n    @override","sourceCodeStart":232,"sourceCodeEnd":268,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/ebcdic_backend.py#L232-L268","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check layout_file.exists() and permissions before constructing the backend","Validate the JSON manually: EbcdicLayout.model_validate_json(Path(layout_file).read_bytes()) to surface the exact validation error","Use an absolute Path for layout_file to avoid working-directory drift","Regenerate the layout JSON against the current EbcdicLayout schema after upgrading Docling"],"exampleFix":"# before\nopts = EbcdicBackendOptions(layout_file=Path('layout.json'))  # relative path, may not exist\n\n# after\nlayout_path = Path('layout.json').resolve()\nEbcdicLayout.model_validate_json(layout_path.read_bytes())  # fail early with a precise error\nopts = EbcdicBackendOptions(layout_file=layout_path)","handlingStrategy":"try-catch","validationCode":"from pathlib import Path\nfrom docling.backend.ebcdic_backend import EbcdicLayout\n\nlayout_file = Path('layout.json').resolve()\nassert layout_file.is_file(), f'layout file missing: {layout_file}'\nEbcdicLayout.model_validate_json(layout_file.read_bytes())  # precise schema errors early","typeGuard":null,"tryCatchPattern":"try:\n    EbcdicLayout.model_validate_json(layout_file.read_bytes())\nexcept ValueError as exc:\n    raise ConfigError(f'invalid EBCDIC layout: {exc}') from exc","preventionTips":["Use absolute Paths for layout files","Validate layout JSON in unit tests whenever the EbcdicLayout schema may have changed"],"tags":["ebcdic","configuration","json","file-io"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}