docling-project/docling · error · ValueError

Cannot specify both picture_description_preset and picture_d

Error message

Cannot specify both picture_description_preset and picture_description_custom_config.

What it means

Model validator on the service options: picture_description_preset and picture_description_custom_config are the new-style, mutually exclusive ways to configure picture description. Supplying both is rejected because a preset already determines the full configuration and a custom config contradicts it.

Source

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

            or self.vlm_pipeline_custom_config is not None
        )

        if legacy_set and new_set:
            raise ValueError(
                "Cannot mix legacy VLM options (vlm_pipeline_model*) with new options "
                "(vlm_pipeline_preset/custom_config). Please use only one approach."
            )

        # Note: Deprecation warnings are now emitted by field validators
        # when the fields are set, not here in the model validator

        return self

    @model_validator(mode="after")
    def validate_picture_description_options(self) -> Self:
        """Ensure preset and custom config are mutually exclusive for picture description."""
        if self.picture_description_preset and self.picture_description_custom_config:
            raise ValueError(
                "Cannot specify both picture_description_preset and "
                "picture_description_custom_config."
            )

        # Check if using legacy fields with new fields
        legacy_set = (
            self.picture_description_local is not None
            or self.picture_description_api is not None
        )
        new_set = (
            self.picture_description_preset is not None
            or self.picture_description_custom_config is not None
        )

        if legacy_set and new_set:
            raise ValueError(
                "Cannot mix legacy picture description options (picture_description_local/api) "
                "with new options (picture_description_preset/custom_config). "

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Send only one of picture_description_preset or picture_description_custom_config.
2. To customize a preset, materialize it into a custom_config, edit, and drop the preset key.
3. Clean merged config dicts of one of the two keys before submission.

Example fix

# before
{'picture_description_preset': 'default', 'picture_description_custom_config': {...}}  # ValueError

# after
{'picture_description_custom_config': {...}}

def picture_preset_exclusive(o: dict) -> bool:
    return not (o.get('picture_description_preset') and o.get('picture_description_custom_config'))

When it happens

Trigger: Options containing both picture_description_preset and picture_description_custom_config — commonly a default preset from a shared template plus custom tuning added per request.

Common situations: Config templates with an opinionated default preset; teams layering custom config objects on top of presets instead of editing the preset contents.

Related errors

• The parameters picture_description_local and picture_descrip
• The parameters vlm_pipeline_model, vlm_pipeline_model_local
• Cannot specify both vlm_pipeline_preset and vlm_pipeline_cus
• Cannot mix legacy picture description options (picture_descr
• set either layout or layout_file, not both

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