{"record":{"id":"efc443f93e53aba1","repo":"docling-project/docling","slug":"the-parameters-vlm-pipeline-model-vlm-pipeline-mo","errorCode":null,"errorMessage":"The parameters vlm_pipeline_model, vlm_pipeline_model_local and vlm_pipeline_model_api are mutually exclusive, only one of them can be set.","messagePattern":"The parameters vlm_pipeline_model, vlm_pipeline_model_local and vlm_pipeline_model_api are mutually exclusive, only one of them can be set\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/datamodel/service/options.py","lineNumber":998,"sourceCode":"            raise ValueError(\n                \"The parameters picture_description_local and picture_description_api are mutually exclusive, only one of them can be set.\"\n            )\n\n        return self\n\n    @model_validator(mode=\"after\")\n    def vlm_model_exclusivity(self) -> Self:\n        # Validate vlm model options\n        num_not_nan = sum(\n            opt is not None\n            for opt in (\n                self.vlm_pipeline_model,\n                self.vlm_pipeline_model_local,\n                self.vlm_pipeline_model_api,\n            )\n        )\n        if num_not_nan > 1:\n            raise ValueError(\n                \"The parameters vlm_pipeline_model, vlm_pipeline_model_local and vlm_pipeline_model_api are mutually exclusive, only one of them can be set.\"\n            )\n\n        return self\n\n    @model_validator(mode=\"after\")\n    def validate_vlm_pipeline_options(self) -> Self:\n        \"\"\"Ensure preset and custom config are mutually exclusive for VLM pipeline.\"\"\"\n        if self.vlm_pipeline_preset and self.vlm_pipeline_custom_config:\n            raise ValueError(\n                \"Cannot specify both vlm_pipeline_preset and vlm_pipeline_custom_config. \"\n                \"Please use one or the other.\"\n            )\n\n        # Check if using legacy fields with new fields\n        legacy_set = (\n            self.vlm_pipeline_model is not None\n            or self.vlm_pipeline_model_local is not None","sourceCodeStart":980,"sourceCodeEnd":1016,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/datamodel/service/options.py#L980-L1016","documentation":"Model validator on the service options: vlm_pipeline_model, vlm_pipeline_model_local, and vlm_pipeline_model_api are three mutually exclusive ways to specify the VLM pipeline model (legacy generic, local, API). Setting more than one raises this error because the service cannot decide which model source to use.","triggerScenarios":"Options payloads containing two or three of the vlm_pipeline_model* keys, e.g., after merging a base config that sets vlm_pipeline_model with a request that adds vlm_pipeline_model_local.","commonSituations":"Legacy configs from older service versions (plain vlm_pipeline_model) combined with newer per-deployment local/API fields; copy-pasted examples stacking multiple model fields.","solutions":["Keep exactly one of vlm_pipeline_model, vlm_pipeline_model_local, vlm_pipeline_model_api.","The vlm_pipeline_model* fields are legacy — consider migrating to vlm_pipeline_preset or vlm_pipeline_custom_config.","Sanitize request payloads by stripping unused model keys before sending."],"exampleFix":"# before\n{'vlm_pipeline_model': 'smoldocling', 'vlm_pipeline_model_local': {...}}  # ValueError\n\n# after\n{'vlm_pipeline_model_local': {...}}","handlingStrategy":"validation","validationCode":"VLM_MODEL_KEYS = ('vlm_pipeline_model', 'vlm_pipeline_model_local', 'vlm_pipeline_model_api')\n\ndef vlm_model_fields_ok(o: dict) -> bool:\n    return sum(o.get(k) is not None for k in VLM_MODEL_KEYS) <= 1","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Send exactly one vlm_pipeline_model* field (or migrate to preset/custom_config).","When layering configs, null out superseded model keys.","Treat these fields as legacy and plan migration to the new API."],"tags":["service","vlm","validation","mutual-exclusion","deprecation"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}