{"record":{"id":"16624c60508eeb97","repo":"docling-project/docling","slug":"expected-transformersvlmengineoptions-got-type-o","errorCode":null,"errorMessage":"Expected TransformersVlmEngineOptions, got {type(options)}","messagePattern":"Expected TransformersVlmEngineOptions, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/vlm/factory.py","lineNumber":85,"sourceCode":"        if not isinstance(options, AutoInlineVlmEngineOptions):\n            raise ValueError(\n                f\"Expected AutoInlineVlmEngineOptions, got {type(options)}\"\n            )\n        return AutoInlineVlmEngine(\n            options,\n            model_spec=model_spec,\n            artifacts_path=artifacts_path,\n            accelerator_options=accelerator_options,\n        )\n\n    elif engine_type == VlmEngineType.TRANSFORMERS:\n        from docling.datamodel.vlm_engine_options import TransformersVlmEngineOptions\n        from docling.models.inference_engines.vlm.transformers_engine import (\n            TransformersVlmEngine,\n        )\n\n        if not isinstance(options, TransformersVlmEngineOptions):\n            raise ValueError(\n                f\"Expected TransformersVlmEngineOptions, got {type(options)}\"\n            )\n        return TransformersVlmEngine(\n            options,\n            model_config=model_config,\n            artifacts_path=artifacts_path,\n            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        )","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/vlm/factory.py#L67-L103","documentation":"create_vlm_engine requires the options class to match the requested engine type. For VlmEngineType.TRANSFORMERS it demands a TransformersVlmEngineOptions instance; anything else raises this ValueError before the engine is constructed.","triggerScenarios":"Calling create_vlm_engine with options.engine_type == VlmEngineType.TRANSFORMERS while options is not TransformersVlmEngineOptions (e.g. VllmVlmEngineOptions or AutoInlineVlmEngineOptions).","commonSituations":"Switching a pipeline from vLLM or MLX to the Transformers engine by editing only the engine_type enum; config deserialization producing the wrong options subclass.","solutions":["Use TransformersVlmEngineOptions (which carries device, dtype, prompts, and transformers-specific knobs) for the TRANSFORMERS engine type","If you intended another runtime, revert engine_type to match the options class you already have","Ensure YAML/JSON config loaders instantiate the options class corresponding to the engine_type field"],"exampleFix":"# before\noptions = VllmVlmEngineOptions(engine_type=VlmEngineType.TRANSFORMERS)\nengine = create_vlm_engine(options=options, ...)\n\n# after\nfrom docling.datamodel.vlm_engine_options import TransformersVlmEngineOptions\noptions = TransformersVlmEngineOptions()  # engine_type defaults to TRANSFORMERS\nengine = create_vlm_engine(options=options, ...)","handlingStrategy":"type-guard","validationCode":"from docling.datamodel.vlm_engine_options import TransformersVlmEngineOptions\nfrom docling.models.inference_engines.vlm.base import VlmEngineType\n\nassert options.engine_type == VlmEngineType.TRANSFORMERS\nassert isinstance(options, TransformersVlmEngineOptions), (\n    f'options/engine_type mismatch: {type(options).__name__}'\n)","typeGuard":"from docling.datamodel.vlm_engine_options import TransformersVlmEngineOptions\n\ndef is_transformers_options(opts: object) -> bool:\n    return isinstance(opts, TransformersVlmEngineOptions)","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 TransformersVlmEngineOptions' in str(e):\n        from docling.datamodel.vlm_engine_options import TransformersVlmEngineOptions\n        engine = create_vlm_engine(options=TransformersVlmEngineOptions(), model_spec=spec, enable_remote_services=False, artifacts_path=None, accelerator_options=acc)\n    else:\n        raise","preventionTips":["Pair engine_type and options class in one place (config schema or builder function)","When switching engines, replace the whole options object, not just the enum","Write a unit test that every pipeline config you ship passes create_vlm_engine"],"tags":["vlm","factory","configuration","type-mismatch","transformers"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}