docling-project/docling · error · ValueError

Cannot mix legacy VLM options (vlm_pipeline_model*) with new

Error message

Cannot mix legacy VLM options (vlm_pipeline_model*) with new options (vlm_pipeline_preset/custom_config). Please use only one approach.

What it means

Model validator on the service options: the legacy VLM model fields (vlm_pipeline_model, vlm_pipeline_model_local, vlm_pipeline_model_api) cannot be combined with the new-style fields (vlm_pipeline_preset, vlm_pipeline_custom_config). Docling migrated VLM configuration to presets/custom configs, and mixing generations of the API is rejected to avoid ambiguity.

Source

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

        if self.vlm_pipeline_preset and self.vlm_pipeline_custom_config:
            raise ValueError(
                "Cannot specify both vlm_pipeline_preset and vlm_pipeline_custom_config. "
                "Please use one or the other."
            )

        # Check if using legacy fields with new fields
        legacy_set = (
            self.vlm_pipeline_model is not None
            or self.vlm_pipeline_model_local is not None
            or self.vlm_pipeline_model_api is not None
        )
        new_set = (
            self.vlm_pipeline_preset is not None
            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."
            )

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Migrate fully to the new style: remove all vlm_pipeline_model* keys and keep only vlm_pipeline_preset or vlm_pipeline_custom_config.
2. If you must stay on the legacy API temporarily, ensure no preset/custom_config keys are present.
3. Add a client-side check that rejects payloads containing keys from both generations before submission.

Example fix

# before
{'vlm_pipeline_model': 'smoldocling', 'vlm_pipeline_preset': 'vlm'}  # ValueError

# after
{'vlm_pipeline_preset': 'vlm'}

LEGACY = ('vlm_pipeline_model', 'vlm_pipeline_model_local', 'vlm_pipeline_model_api')
NEW = ('vlm_pipeline_preset', 'vlm_pipeline_custom_config')

def vlm_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 carrying any vlm_pipeline_model* key together with vlm_pipeline_preset or vlm_pipeline_custom_config — e.g., an old client config (model fields) sent to an upgraded service that also injects a preset, or a config migration done halfway.

Common situations: Upgrading a docling-service deployment: existing request payloads still contain legacy vlm_pipeline_model while the new deployment templates add presets; client libraries lagging behind service version.

Related errors

• The parameters vlm_pipeline_model, vlm_pipeline_model_local
• Cannot mix legacy picture description options (picture_descr
• The parameters picture_description_local and picture_descrip
• Cannot specify both vlm_pipeline_preset and vlm_pipeline_cus
• Invalid JSON for nested config field: {exc}

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