{"record":{"id":"772d736e5c6c4618","repo":"docling-project/docling","slug":"expected-apivlmengineoptions-got-type-options","errorCode":null,"errorMessage":"Expected ApiVlmEngineOptions, got {type(options)}","messagePattern":"Expected ApiVlmEngineOptions, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/vlm/factory.py","lineNumber":125,"sourceCode":"        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,\n            model_config=model_config,\n        )\n\n    else:\n        raise ValueError(f\"Unsupported engine type: {engine_type}\")\n","sourceCodeStart":107,"sourceCodeEnd":134,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/vlm/factory.py#L107-L134","documentation":"create_vlm_engine validates the options/engine-type pairing for API variants (VlmEngineType.is_api_variant). API engines such as ApiVlmEngine require ApiVlmEngineOptions; any other options subclass raises this ValueError.","triggerScenarios":"Calling create_vlm_engine where VlmEngineType.is_api_variant(options.engine_type) is true (API engine types) but options is not ApiVlmEngineOptions — e.g. a local-runtime options class with its engine_type switched to the API variant.","commonSituations":"Moving from a local model to a hosted/local OpenAI-compatible endpoint and only changing engine_type; reusing Transformers options because they also have url-ish fields.","solutions":["Construct ApiVlmEngineOptions (with url set) for API engine types","If you meant a local runtime, keep the local options class and its matching engine_type","Verify enable_remote_services is true when the endpoint is remote, since ApiVlmEngine receives that flag at creation"],"exampleFix":"# before\noptions = TransformersVlmEngineOptions(engine_type=VlmEngineType.API)\nengine = create_vlm_engine(options=options, enable_remote_services=True, ...)\n\n# after\nfrom docling.datamodel.vlm_engine_options import ApiVlmEngineOptions\noptions = ApiVlmEngineOptions(url='http://localhost:8000/v1/chat/completions')\nengine = create_vlm_engine(options=options, enable_remote_services=True, ...)","handlingStrategy":"type-guard","validationCode":"from docling.datamodel.vlm_engine_options import ApiVlmEngineOptions\nfrom docling.models.inference_engines.vlm.base import VlmEngineType\n\nassert VlmEngineType.is_api_variant(options.engine_type)\nassert isinstance(options, ApiVlmEngineOptions), (\n    f'options/engine_type mismatch: {type(options).__name__}'\n)","typeGuard":"from docling.datamodel.vlm_engine_options import ApiVlmEngineOptions\n\ndef is_api_options(opts: object) -> bool:\n    return isinstance(opts, ApiVlmEngineOptions)","tryCatchPattern":"try:\n    engine = create_vlm_engine(options=options, model_spec=spec, enable_remote_services=True, artifacts_path=None, accelerator_options=acc)\nexcept ValueError as e:\n    if 'Expected ApiVlmEngineOptions' in str(e):\n        from docling.datamodel.vlm_engine_options import ApiVlmEngineOptions\n        engine = create_vlm_engine(options=ApiVlmEngineOptions(url='http://localhost:8000/v1/chat/completions'), model_spec=spec, enable_remote_services=True, artifacts_path=None, accelerator_options=acc)\n    else:\n        raise","preventionTips":["When moving from local to API inference, swap the entire options object (including url), not just engine_type","Centralize the engine_type -> options-class mapping in your config loader","Ensure enable_remote_services=True for hosted endpoints or the API path will be blocked elsewhere"],"tags":["vlm","factory","configuration","type-mismatch","api"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}