docling-project/docling · error · ValueError

Expected MlxVlmEngineOptions, got {type(options)}

Error message

Expected MlxVlmEngineOptions, got {type(options)}

What it means

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.

Source

Thrown at docling/models/inference_engines/vlm/factory.py:100

        )

        if not isinstance(options, TransformersVlmEngineOptions):
            raise ValueError(
                f"Expected TransformersVlmEngineOptions, got {type(options)}"
            )
        return TransformersVlmEngine(
            options,
            model_config=model_config,
            artifacts_path=artifacts_path,
            accelerator_options=accelerator_options,
        )

    elif engine_type == VlmEngineType.MLX:
        from docling.datamodel.vlm_engine_options import MlxVlmEngineOptions
        from docling.models.inference_engines.vlm.mlx_engine import MlxVlmEngine

        if not isinstance(options, MlxVlmEngineOptions):
            raise ValueError(f"Expected MlxVlmEngineOptions, got {type(options)}")
        return MlxVlmEngine(
            options, model_config=model_config, artifacts_path=artifacts_path
        )

    elif engine_type == VlmEngineType.VLLM:
        from docling.datamodel.vlm_engine_options import VllmVlmEngineOptions
        from docling.models.inference_engines.vlm.vllm_engine import VllmVlmEngine

        if not isinstance(options, VllmVlmEngineOptions):
            raise ValueError(f"Expected VllmVlmEngineOptions, got {type(options)}")
        return VllmVlmEngine(
            options,
            model_config=model_config,
            artifacts_path=artifacts_path,
            accelerator_options=accelerator_options,
        )

    elif VlmEngineType.is_api_variant(engine_type):

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Construct MlxVlmEngineOptions for the MLX engine type
2. Keep engine_type and the options class paired: change both or neither
3. Note MLX only works on Apple Silicon; on other hardware pick TRANSFORMERS or VLLM with their own options classes

Example fix

# before
options = TransformersVlmEngineOptions(engine_type=VlmEngineType.MLX)
engine = create_vlm_engine(options=options, ...)

# after
from docling.datamodel.vlm_engine_options import MlxVlmEngineOptions
options = MlxVlmEngineOptions()
engine = create_vlm_engine(options=options, ...)

import platform
from docling.datamodel.vlm_engine_options import MlxVlmEngineOptions
from docling.models.inference_engines.vlm.base import VlmEngineType

assert options.engine_type == VlmEngineType.MLX
assert isinstance(options, MlxVlmEngineOptions), (
    f'options/engine_type mismatch: {type(options).__name__}'
)
assert platform.system() == 'Darwin' and platform.machine() == 'arm64', 'MLX requires Apple Silicon'

from docling.datamodel.vlm_engine_options import MlxVlmEngineOptions

def is_mlx_options(opts: object) -> bool:
    return isinstance(opts, MlxVlmEngineOptions)

try:
    engine = create_vlm_engine(options=options, model_spec=spec, enable_remote_services=False, artifacts_path=None, accelerator_options=acc)
except ValueError as e:
    if 'Expected MlxVlmEngineOptions' in str(e):
        from docling.datamodel.vlm_engine_options import MlxVlmEngineOptions
        engine = create_vlm_engine(options=MlxVlmEngineOptions(), model_spec=spec, enable_remote_services=False, artifacts_path=None, accelerator_options=acc)
    else:
        raise

When it happens

Trigger: Calling create_vlm_engine with options.engine_type == VlmEngineType.MLX while options is not MlxVlmEngineOptions — typically TransformersVlmEngineOptions or ApiVlmEngineOptions reused from another pipeline.

Common situations: 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.

Related errors

• Expected AutoInlineVlmEngineOptions, got {type(options)}
• Expected TransformersVlmEngineOptions, got {type(options)}
• Expected VllmVlmEngineOptions, got {type(options)}
• Expected ApiVlmEngineOptions, got {type(options)}
• Expected OnnxRuntimeObjectDetectionEngineOptions, got {type(

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/0fc3e2352a75fe17. Report an issue: GitHub.