docling-project/docling · error · ValueError

Cannot mix legacy picture description options (picture_descr

Error message

Cannot mix legacy picture description options (picture_description_local/api) with new options (picture_description_preset/custom_config). Please use only one approach.

What it means

Model validator on the service options: legacy picture description fields (picture_description_local, picture_description_api) cannot be mixed with new-style fields (picture_description_preset, picture_description_custom_config). As with the VLM fields, docling migrated this configuration surface and rejects half-migrated payloads that set keys from both generations.

Source

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

        """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). "
                "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_code_formula_options(self) -> Self:
        """Ensure preset and custom config are mutually exclusive for code/formula."""
        if self.code_formula_preset and self.code_formula_custom_config:
            raise ValueError(
                "Cannot specify both code_formula_preset and code_formula_custom_config."
            )

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Complete the migration: remove picture_description_local/picture_description_api and use only preset or custom_config.
2. If staying legacy temporarily, ensure no preset/custom_config keys are set.
3. Add a pre-flight payload check rejecting mixed-generation picture-description keys.

Example fix

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

# after
{'picture_description_preset': 'default'}

LEGACY = ('picture_description_local', 'picture_description_api')
NEW = ('picture_description_preset', 'picture_description_custom_config')

def picture_generations_not_mixed(o: dict) -> bool:
    return not (any(o.get(k) is not None for k in LEGACY)
                and any(o.get(k) is not None for k in NEW))

When it happens

Trigger: Options containing picture_description_local or picture_description_api together with picture_description_preset or picture_description_custom_config — e.g., legacy client payload plus new deployment defaults, or a config migration that added the new keys without removing the old ones.

Common situations: Service upgrades where stored request templates still carry picture_description_api (deprecated) while new tooling injects presets; gradual migration of client fleets hitting the new validation.

Related errors

• The parameters picture_description_local and picture_descrip
• Cannot mix legacy VLM options (vlm_pipeline_model*) with new
• The parameters vlm_pipeline_model, vlm_pipeline_model_local
• Cannot specify both picture_description_preset and picture_d
• Invalid JSON for nested config field: {exc}

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