docling-project/docling · error · ValueError

The parameters picture_description_local and picture_descrip

Error message

The parameters picture_description_local and picture_description_api are mutually exclusive, only one of them can be set.

What it means

Model validator on the service options: picture_description_local (locally-hosted picture description model) and picture_description_api (remote API endpoint) are two alternative ways to configure picture description, and both being non-None is rejected. Only one picture-description backend can be active.

Source

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

    def validate_vlm_pipeline_model_api(cls, v):
        """Emit deprecation warning when vlm_pipeline_model_api is set."""
        if v is not None:
            warnings.warn(
                "vlm_pipeline_model_api is deprecated. "
                "Please migrate to vlm_pipeline_preset or vlm_pipeline_custom_config.",
                DeprecationWarning,
                stacklevel=2,
            )
        return v

    @model_validator(mode="after")
    def picture_description_exclusivity(self) -> Self:
        # Validate picture description options
        if (
            self.picture_description_local is not None
            and self.picture_description_api is not None
        ):
            raise ValueError(
                "The parameters picture_description_local and picture_description_api are mutually exclusive, only one of them can be set."
            )

        return self

    @model_validator(mode="after")
    def vlm_model_exclusivity(self) -> Self:
        # Validate vlm model options
        num_not_nan = sum(
            opt is not None
            for opt in (
                self.vlm_pipeline_model,
                self.vlm_pipeline_model_local,
                self.vlm_pipeline_model_api,
            )
        )
        if num_not_nan > 1:
            raise ValueError(

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Remove one of the two fields so exactly one of picture_description_local / picture_description_api remains.
2. Note picture_description_api is deprecated — prefer picture_description_local or the new picture_description_preset/custom_config fields.
3. If merging configs, drop deprecated keys before submission.

Example fix

# before
options = {'picture_description_local': {...}, 'picture_description_api': {...}}  # ValueError

# after
options = {'picture_description_local': {...}}

def picture_desc_options_ok(o: dict) -> bool:
    return not (o.get('picture_description_local') is not None
                and o.get('picture_description_api') is not None)

When it happens

Trigger: Submitting request options containing both picture_description_local and picture_description_api — typically when a client template fills in both and comments one out incorrectly, or when a migrated config keeps the deprecated picture_description_api while adding the new local option.

Common situations: Transitioning deployments from API-based picture description to local models; config overlays merging defaults with per-request overrides producing both keys.

Related errors

• The parameters vlm_pipeline_model, vlm_pipeline_model_local
• Cannot specify both picture_description_preset and picture_d
• Cannot mix legacy picture description options (picture_descr
• Cannot specify both vlm_pipeline_preset and vlm_pipeline_cus
• Cannot mix legacy VLM options (vlm_pipeline_model*) with new

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