{"record":{"id":"bdb8ba277a3dff81","repo":"docling-project/docling","slug":"the-parameters-picture-description-local-and-pictu","errorCode":null,"errorMessage":"The parameters picture_description_local and picture_description_api are mutually exclusive, only one of them can be set.","messagePattern":"The parameters picture_description_local and picture_description_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":980,"sourceCode":"    def validate_vlm_pipeline_model_api(cls, v):\n        \"\"\"Emit deprecation warning when vlm_pipeline_model_api is set.\"\"\"\n        if v is not None:\n            warnings.warn(\n                \"vlm_pipeline_model_api is deprecated. \"\n                \"Please migrate to vlm_pipeline_preset or vlm_pipeline_custom_config.\",\n                DeprecationWarning,\n                stacklevel=2,\n            )\n        return v\n\n    @model_validator(mode=\"after\")\n    def picture_description_exclusivity(self) -> Self:\n        # Validate picture description options\n        if (\n            self.picture_description_local is not None\n            and self.picture_description_api is not None\n        ):\n            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(","sourceCodeStart":962,"sourceCodeEnd":998,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/datamodel/service/options.py#L962-L998","documentation":"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.","triggerScenarios":"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.","commonSituations":"Transitioning deployments from API-based picture description to local models; config overlays merging defaults with per-request overrides producing both keys.","solutions":["Remove one of the two fields so exactly one of picture_description_local / picture_description_api remains.","Note picture_description_api is deprecated — prefer picture_description_local or the new picture_description_preset/custom_config fields.","If merging configs, drop deprecated keys before submission."],"exampleFix":"# before\noptions = {'picture_description_local': {...}, 'picture_description_api': {...}}  # ValueError\n\n# after\noptions = {'picture_description_local': {...}}","handlingStrategy":"validation","validationCode":"def picture_desc_options_ok(o: dict) -> bool:\n    return not (o.get('picture_description_local') is not None\n                and o.get('picture_description_api') is not None)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Configure exactly one picture-description source.","picture_description_api is deprecated — migrate to local or preset/custom_config.","Strip deprecated keys when merging configs."],"tags":["service","picture-description","validation","mutual-exclusion","deprecation"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}