{"record":{"id":"1da03a65f7802b64","repo":"docling-project/docling","slug":"expected-autoinlinevlmengineoptions-got-type-opt","errorCode":null,"errorMessage":"Expected AutoInlineVlmEngineOptions, got {type(options)}","messagePattern":"Expected AutoInlineVlmEngineOptions, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/vlm/factory.py","lineNumber":68,"sourceCode":"    # Generate model_config from model_spec if provided\n    model_config: Optional[EngineModelConfig] = None\n    if model_spec is not None and engine_type != VlmEngineType.AUTO_INLINE:\n        # AUTO_INLINE handles model_spec internally\n        model_config = model_spec.get_engine_config(engine_type)\n\n        # For API engines, add API params to extra_config\n        if VlmEngineType.is_api_variant(engine_type):\n            api_params = model_spec.get_api_params(engine_type)\n            model_config.extra_config[\"api_params\"] = api_params\n\n    if engine_type == VlmEngineType.AUTO_INLINE:\n        from docling.datamodel.vlm_engine_options import AutoInlineVlmEngineOptions\n        from docling.models.inference_engines.vlm.auto_inline_engine import (\n            AutoInlineVlmEngine,\n        )\n\n        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)}\"","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/vlm/factory.py#L50-L86","documentation":"create_vlm_engine dispatches on options.engine_type and requires the options object class to match the engine type. For VlmEngineType.AUTO_INLINE it demands an AutoInlineVlmEngineOptions instance; any other options subclass raises this ValueError. This guards against mixing an engine type with options meant for a different runtime.","triggerScenarios":"Calling create_vlm_engine(options=..., model_spec=...) where options.engine_type == VlmEngineType.AUTO_INLINE but options is e.g. ApiVlmEngineOptions, TransformersVlmEngineOptions, or a hand-rolled BaseVlmEngineOptions subclass.","commonSituations":"Copy-pasting a pipeline config and changing only the engine_type string while keeping the old options class; passing a generic options object because the config loader did not map the type correctly.","solutions":["Pass AutoInlineVlmEngineOptions when engine_type is AUTO_INLINE","If you meant a different runtime, keep the options class and set its matching engine_type instead","Check that the options class and engine_type come from the same construction site in your config code"],"exampleFix":"# before\noptions = ApiVlmEngineOptions(engine_type=VlmEngineType.AUTO_INLINE)\nengine = create_vlm_engine(options=options, ...)\n\n# after\nfrom docling.datamodel.vlm_engine_options import AutoInlineVlmEngineOptions\noptions = AutoInlineVlmEngineOptions()  # engine_type is AUTO_INLINE by default\nengine = create_vlm_engine(options=options, ...)","handlingStrategy":"type-guard","validationCode":"from docling.datamodel.vlm_engine_options import AutoInlineVlmEngineOptions\nfrom docling.models.inference_engines.vlm.base import VlmEngineType\n\nassert options.engine_type == VlmEngineType.AUTO_INLINE\nassert isinstance(options, AutoInlineVlmEngineOptions), (\n    f'options/engine_type mismatch: {type(options).__name__}'\n)","typeGuard":"from docling.datamodel.vlm_engine_options import AutoInlineVlmEngineOptions\n\ndef is_auto_inline_options(opts: object) -> bool:\n    return isinstance(opts, AutoInlineVlmEngineOptions)","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 AutoInlineVlmEngineOptions' in str(e):\n        # fix the options class and retry once\n        from docling.datamodel.vlm_engine_options import AutoInlineVlmEngineOptions\n        engine = create_vlm_engine(options=AutoInlineVlmEngineOptions(), model_spec=spec, enable_remote_services=False, artifacts_path=None, accelerator_options=acc)\n    else:\n        raise","preventionTips":["Construct options and engine_type from a single factory function so they cannot diverge","Add a startup assertion mapping each engine_type to its expected options class","Review config-migration diffs for engine_type changes that leave the options class behind"],"tags":["vlm","factory","configuration","type-mismatch"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}