docling-project/docling · error · ValueError

set either layout or layout_file, not both

Error message

set either layout or layout_file, not both

What it means

Pydantic model_validator on EbcdicBackendOptions: layout (an inline EbcdicLayout object) and layout_file (a path to a layout definition) are the two mutually exclusive ways to supply the record schema. Setting both is ambiguous, so the model raises immediately.

Source

Thrown at docling/datamodel/backend_options.py:602

        Optional[EbcdicLayout], Field(description="Parsing rules for the file.")
    ] = None
    layout_file: Annotated[
        Optional[Path],
        Field(description="Path to a JSON file holding the parsing rules."),
    ] = None
    max_records: Annotated[
        Optional[PositiveInt],
        Field(description="Stop after this many records. Unset reads the whole file."),
    ] = None
    strip_control_characters: Annotated[
        bool,
        Field(description="Drop control characters from decoded character data."),
    ] = True

    @model_validator(mode="after")
    def _validate_layout_source(self) -> "EbcdicBackendOptions":
        if self.layout is not None and self.layout_file is not None:
            raise ValueError("set either layout or layout_file, not both")
        return self


BackendOptions = Annotated[
    Union[
        DeclarativeBackendOptions,
        EbcdicBackendOptions,
        EpubBackendOptions,
        HTMLBackendOptions,
        MarkdownBackendOptions,
        PdfBackendOptions,
        ThreadedDoclingParseBackendOptions,
        MetsGbsBackendOptions,
        MsExcelBackendOptions,
        MsPowerpointBackendOptions,
        MsWordBackendOptions,
        OdsBackendOptions,
        LatexBackendOptions,

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Keep exactly one source: either the inline layout object or layout_file, not both.
2. If overriding, explicitly set the other to None: EbcdicBackendOptions(layout=new_layout, layout_file=None).
3. When loading from a shared config, pop the unused key before constructing options.

Example fix

# before
opts = EbcdicBackendOptions(layout=layout, layout_file=Path('layout.json'))  # ValueError

# after
opts = EbcdicBackendOptions(layout=layout)

cfg.pop('layout_file', None)  # or cfg.pop('layout', None)
opts = EbcdicBackendOptions(**cfg)  # exactly one layout source

When it happens

Trigger: Constructing EbcdicBackendOptions(layout=my_layout, layout_file=Path('layout.json')) — typically when a shared config template already sets layout_file and code also passes an inline layout (or vice versa).

Common situations: Pipelines built on a base options object that includes layout_file, then per-run code adds a layout override; merging CLI flags with programmatic options.

Related errors

• record_type_field is required for a layout with several reco
• every record needs a selector when record_type_field is set
• record selectors must be unique
• Invalid device option. Use `auto`, `cpu`, `mps`, `xpu`, `cud
• Model `{self.repo_id}` is English-only and does not support

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