{"record":{"id":"622f3af022eb0440","repo":"docling-project/docling","slug":"expected-vllmvlmengineoptions-got-type-options","errorCode":null,"errorMessage":"Expected VllmVlmEngineOptions, got {type(options)}","messagePattern":"Expected VllmVlmEngineOptions, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/vlm/factory.py","lineNumber":110,"sourceCode":"            accelerator_options=accelerator_options,\n        )\n\n    elif engine_type == VlmEngineType.MLX:\n        from docling.datamodel.vlm_engine_options import MlxVlmEngineOptions\n        from docling.models.inference_engines.vlm.mlx_engine import MlxVlmEngine\n\n        if not isinstance(options, MlxVlmEngineOptions):\n            raise ValueError(f\"Expected MlxVlmEngineOptions, got {type(options)}\")\n        return MlxVlmEngine(\n            options, model_config=model_config, artifacts_path=artifacts_path\n        )\n\n    elif engine_type == VlmEngineType.VLLM:\n        from docling.datamodel.vlm_engine_options import VllmVlmEngineOptions\n        from docling.models.inference_engines.vlm.vllm_engine import VllmVlmEngine\n\n        if not isinstance(options, VllmVlmEngineOptions):\n            raise ValueError(f\"Expected VllmVlmEngineOptions, got {type(options)}\")\n        return VllmVlmEngine(\n            options,\n            model_config=model_config,\n            artifacts_path=artifacts_path,\n            accelerator_options=accelerator_options,\n        )\n\n    elif VlmEngineType.is_api_variant(engine_type):\n        from docling.datamodel.vlm_engine_options import ApiVlmEngineOptions\n        from docling.models.inference_engines.vlm.api_openai_compatible_engine import (\n            ApiVlmEngine,\n        )\n\n        if not isinstance(options, ApiVlmEngineOptions):\n            raise ValueError(f\"Expected ApiVlmEngineOptions, got {type(options)}\")\n        return ApiVlmEngine(\n            enable_remote_services=enable_remote_services,\n            options=options,","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/vlm/factory.py#L92-L128","documentation":"create_vlm_engine validates the options/engine-type pairing. For VlmEngineType.VLLM it requires VllmVlmEngineOptions; passing any other options subclass raises this ValueError before the VllmVlmEngine is built.","triggerScenarios":"Calling create_vlm_engine with options.engine_type == VlmEngineType.VLLM while options is not VllmVlmEngineOptions (e.g. options built for the Transformers or API runtime).","commonSituations":"Switching from local Transformers inference to vLLM for throughput by editing only engine_type; deserialized config mapping to the wrong options class.","solutions":["Use VllmVlmEngineOptions for the VLLM engine type","If keeping your current options class, set its own engine_type instead of VLLM","Make sure each pipeline config builds the options class that matches its declared engine"],"exampleFix":"# before\noptions = TransformersVlmEngineOptions(engine_type=VlmEngineType.VLLM)\nengine = create_vlm_engine(options=options, ...)\n\n# after\nfrom docling.datamodel.vlm_engine_options import VllmVlmEngineOptions\noptions = VllmVlmEngineOptions()\nengine = create_vlm_engine(options=options, ...)","handlingStrategy":"type-guard","validationCode":"from docling.datamodel.vlm_engine_options import VllmVlmEngineOptions\nfrom docling.models.inference_engines.vlm.base import VlmEngineType\n\nassert options.engine_type == VlmEngineType.VLLM\nassert isinstance(options, VllmVlmEngineOptions), (\n    f'options/engine_type mismatch: {type(options).__name__}'\n)","typeGuard":"from docling.datamodel.vlm_engine_options import VllmVlmEngineOptions\n\ndef is_vllm_options(opts: object) -> bool:\n    return isinstance(opts, VllmVlmEngineOptions)","tryCatchPattern":"try:\n    engine = create_vlm_engine(options=options, model_spec=spec, enable_remote_services=False, artifacts_path=None, accelerator_options=acc)\nexcept ValueError as e:\n    if 'Expected VllmVlmEngineOptions' in str(e):\n        from docling.datamodel.vlm_engine_options import VllmVlmEngineOptions\n        engine = create_vlm_engine(options=VllmVlmEngineOptions(), model_spec=spec, enable_remote_services=False, artifacts_path=None, accelerator_options=acc)\n    else:\n        raise","preventionTips":["Treat engine_type + options class as one unit in config validation","Automate the pairing with a dict of engine_type -> options class used at construction","Smoke-test pipeline creation in CI so mismatches surface before production"],"tags":["vlm","factory","configuration","type-mismatch","vllm"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}