{"record":{"id":"1defb6c25c61f8ee","repo":"docling-project/docling","slug":"unsupported-vlm-options-type-type-base-vlm-optio","errorCode":null,"errorMessage":"Unsupported VLM options type: {type(base_vlm_options)}","messagePattern":"Unsupported VLM options type: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/experimental/pipeline/threaded_layout_vlm_pipeline.py","lineNumber":212,"sourceCode":"                    artifacts_path=art_path,\n                    accelerator_options=self.pipeline_options.accelerator_options,\n                    vlm_options=vlm_options,\n                )\n            elif vlm_options.inference_framework == InferenceFramework.VLLM:\n                from docling.models.vlm_pipeline_models.vllm_model import VllmVlmModel\n\n                self.vlm_model = VllmVlmModel(\n                    enabled=True,\n                    artifacts_path=art_path,\n                    accelerator_options=self.pipeline_options.accelerator_options,\n                    vlm_options=vlm_options,\n                )\n            else:\n                raise ValueError(\n                    f\"Unsupported VLM inference framework: {vlm_options.inference_framework}\"\n                )\n        else:\n            raise ValueError(f\"Unsupported VLM options type: {type(base_vlm_options)}\")\n\n    def _resolve_artifacts_path(self) -> Optional[Path]:\n        \"\"\"Resolve artifacts path from options or settings.\"\"\"\n        if self.pipeline_options.artifacts_path:\n            p = Path(self.pipeline_options.artifacts_path).expanduser()\n        elif settings.artifacts_path:\n            p = Path(settings.artifacts_path).expanduser()\n        else:\n            return None\n        if not p.is_dir():\n            raise RuntimeError(\n                f\"{p} does not exist or is not a directory containing the required models\"\n            )\n        return p\n\n    def _create_run_ctx(self) -> RunContext:\n        \"\"\"Create pipeline stages and wire them together.\"\"\"\n        opts = self.pipeline_options","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/experimental/pipeline/threaded_layout_vlm_pipeline.py#L194-L230","documentation":"ValueError raised in ThreadedLayoutVlmPipeline's VLM-model setup when the base VLM options object passed via pipeline_options.vlm_options is not the options type this pipeline expects. The pipeline needs to downcast to a concrete options class to read model settings; an unexpected type means configuration was mixed between pipeline families.","triggerScenarios":"Assigning a generic or different-family VlmOptions subclass (e.g. options written for the standard VlmPipeline or an API-specific options class) to ThreadedLayoutVlmPipelineOptions.vlm_options.","commonSituations":"Sharing one options object across standard and experimental pipelines; upgrading Docling and the expected concrete options class changed name/shape.","solutions":["Pass the exact VLM options type required by ThreadedLayoutVlmPipelineOptions (see its field annotation / the isinstance checks in the model factory).","Construct fresh vlm_options per pipeline instead of reusing a global config object.","If your options target the standard VLM flow, switch to StandardPdfPipeline with VlmPipeline rather than the threaded pipeline."],"exampleFix":"# before\nshared = StandardVlmOptions(model_name='...')  # wrong family\nopts = ThreadedLayoutVlmPipelineOptions(vlm_options=shared)\n\n# after\nfrom docling.datamodel.pipeline_options_vlm_model import VlmOptions\nopts = ThreadedLayoutVlmPipelineOptions(\n    vlm_options=VlmOptions(model_name='...', response_format=ResponseFormat.DOCTAGS)\n)","handlingStrategy":"type-guard","validationCode":"from docling.experimental.datamodel.threaded_layout_vlm_pipeline_options import ThreadedLayoutVlmPipelineOptions\nassert isinstance(pipeline_opts, ThreadedLayoutVlmPipelineOptions), 'wrong options class for this pipeline'","typeGuard":"def is_threaded_options(obj) -> bool:\n    return isinstance(obj, ThreadedLayoutVlmPipelineOptions)","tryCatchPattern":"try:\n    pipeline = ThreadedLayoutVlmPipeline(opts)\nexcept ValueError as e:\n    if 'Unsupported VLM options type' in str(e):\n        raise SystemExit('build fresh ThreadedLayoutVlmPipelineOptions; do not reuse standard-pipeline options')","preventionTips":["Build one dedicated options object per pipeline type; never reuse across families.","After upgrades, re-instantiate options classes rather than patching old instances."],"tags":["vlm","type-mismatch","pipeline-options"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}