{"record":{"id":"0fc3e2352a75fe17","repo":"docling-project/docling","slug":"expected-mlxvlmengineoptions-got-type-options","errorCode":null,"errorMessage":"Expected MlxVlmEngineOptions, got {type(options)}","messagePattern":"Expected MlxVlmEngineOptions, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/vlm/factory.py","lineNumber":100,"sourceCode":"        )\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        )\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):","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/vlm/factory.py#L82-L118","documentation":"create_vlm_engine validates that the options class matches the engine type. For VlmEngineType.MLX (Apple Silicon MLX runtime) it requires MlxVlmEngineOptions; any other options subclass raises this ValueError.","triggerScenarios":"Calling create_vlm_engine with options.engine_type == VlmEngineType.MLX while options is not MlxVlmEngineOptions — typically TransformersVlmEngineOptions or ApiVlmEngineOptions reused from another pipeline.","commonSituations":"Migrating a config from the Transformers engine to MLX on a Mac and changing only the engine enum; sharing one options object across pipeline variants.","solutions":["Construct MlxVlmEngineOptions for the MLX engine type","Keep engine_type and the options class paired: change both or neither","Note MLX only works on Apple Silicon; on other hardware pick TRANSFORMERS or VLLM with their own options classes"],"exampleFix":"# before\noptions = TransformersVlmEngineOptions(engine_type=VlmEngineType.MLX)\nengine = create_vlm_engine(options=options, ...)\n\n# after\nfrom docling.datamodel.vlm_engine_options import MlxVlmEngineOptions\noptions = MlxVlmEngineOptions()\nengine = create_vlm_engine(options=options, ...)","handlingStrategy":"type-guard","validationCode":"import platform\nfrom docling.datamodel.vlm_engine_options import MlxVlmEngineOptions\nfrom docling.models.inference_engines.vlm.base import VlmEngineType\n\nassert options.engine_type == VlmEngineType.MLX\nassert isinstance(options, MlxVlmEngineOptions), (\n    f'options/engine_type mismatch: {type(options).__name__}'\n)\nassert platform.system() == 'Darwin' and platform.machine() == 'arm64', 'MLX requires Apple Silicon'","typeGuard":"from docling.datamodel.vlm_engine_options import MlxVlmEngineOptions\n\ndef is_mlx_options(opts: object) -> bool:\n    return isinstance(opts, MlxVlmEngineOptions)","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 MlxVlmEngineOptions' in str(e):\n        from docling.datamodel.vlm_engine_options import MlxVlmEngineOptions\n        engine = create_vlm_engine(options=MlxVlmEngineOptions(), model_spec=spec, enable_remote_services=False, artifacts_path=None, accelerator_options=acc)\n    else:\n        raise","preventionTips":["Gate MLX configs behind an Apple Silicon check in your deployment scripts","Keep per-engine options constructors in one mapping: {VlmEngineType.MLX: MlxVlmEngineOptions, ...}","Never mutate engine_type on an existing options instance"],"tags":["vlm","factory","configuration","type-mismatch","mlx","apple-silicon"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}