docling-project/docling · error · ValueError

Cannot specify both picture_classification_preset and pictur

Error message

Cannot specify both picture_classification_preset and picture_classification_custom_config.

What it means

A Pydantic model validator rejects service options that set both picture_classification_preset and picture_classification_custom_config. The picture classification stage is configured either by a named preset or by a custom config, and supplying both is a modeling error caught during validation.

Source

Thrown at docling/datamodel/service/options.py:1092

        return self

    @model_validator(mode="after")
    def validate_layout_options(self) -> Self:
        """Ensure preset and custom config are mutually exclusive for layout."""
        if self.layout_preset and self.layout_custom_config:
            raise ValueError(
                "Cannot specify both layout_preset and layout_custom_config."
            )
        return self

    @model_validator(mode="after")
    def validate_picture_classification_options(self) -> Self:
        """Ensure preset and custom config are mutually exclusive for picture classification."""
        if (
            self.picture_classification_preset
            and self.picture_classification_custom_config
        ):
            raise ValueError(
                "Cannot specify both picture_classification_preset and "
                "picture_classification_custom_config."
            )
        return self

    @model_validator(mode="after")
    def validate_ocr_options(self) -> Self:
        """Handle deprecated ocr_engine and sync to ocr_preset."""
        # If ocr_engine is explicitly set (not default), sync to ocr_preset
        if (
            hasattr(self, "__pydantic_fields_set__")
            and "ocr_engine" in self.__pydantic_fields_set__
            and "ocr_preset" not in self.__pydantic_fields_set__
        ):
            warnings.warn(
                "ocr_engine is deprecated and will be removed in a future version. "
                "Use ocr_preset instead.",
                DeprecationWarning,

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Send only one of picture_classification_preset or picture_classification_custom_config.
2. If the custom config was copied from a preset just to tweak one value, remove the custom config and use the preset.
3. Validate the outgoing payload shape in a shared helper so the pair is mutually exclusive by construction.

Example fix

# before
opts = ConvertOptions(
    picture_classification_preset="default",
    picture_classification_custom_config={"labels": ["chart"]},
)

# after
opts = ConvertOptions(
    picture_classification_custom_config={"labels": ["chart"]},
)

def assert_picture_classification(opts: dict) -> None:
    assert not (
        opts.get("picture_classification_preset")
        and opts.get("picture_classification_custom_config")
    ), "picture_classification_preset and picture_classification_custom_config are mutually exclusive"

try:
    ConvertOptions(**cfg)
except ValidationError as e:
    if "picture_classification" in str(e):
        # strip whichever field the user did not intend
        raise ValueError("Pick preset OR custom config for picture classification") from e
    raise

When it happens

Trigger: Building the options model with both picture_classification_preset and picture_classification_custom_config set, e.g. ConvertOptions(picture_classification_preset='default', picture_classification_custom_config={'labels': [...]}).

Common situations: Reusing a full example config that contained a preset while adding a custom classifier config for a new use case; config inheritance where a base sets the preset and a child adds the custom dict; GUI form builders that submit every field regardless of which section the user filled in.

Related errors

• Cannot specify both code_formula_preset and code_formula_cus
• Cannot specify both layout_preset and layout_custom_config.
• Cannot specify both chunking_preset and chunking_options.
• Cannot specify both ocr_preset and ocr_custom_config.
• Invalid device option. Use `auto`, `cpu`, `mps`, `xpu`, `cud

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