docling-project/docling · error · ValueError

Expected VllmVlmEngineOptions, got {type(options)}

Error message

Expected VllmVlmEngineOptions, got {type(options)}

What it means

create_vlm_engine validates the options/engine-type pairing. For VlmEngineType.VLLM it requires VllmVlmEngineOptions; passing any other options subclass raises this ValueError before the VllmVlmEngine is built.

Source

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

            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):
        from docling.datamodel.vlm_engine_options import ApiVlmEngineOptions
        from docling.models.inference_engines.vlm.api_openai_compatible_engine import (
            ApiVlmEngine,
        )

        if not isinstance(options, ApiVlmEngineOptions):
            raise ValueError(f"Expected ApiVlmEngineOptions, got {type(options)}")
        return ApiVlmEngine(
            enable_remote_services=enable_remote_services,
            options=options,

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Use VllmVlmEngineOptions for the VLLM engine type
2. If keeping your current options class, set its own engine_type instead of VLLM
3. Make sure each pipeline config builds the options class that matches its declared engine

Example fix

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

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

from docling.datamodel.vlm_engine_options import VllmVlmEngineOptions
from docling.models.inference_engines.vlm.base import VlmEngineType

assert options.engine_type == VlmEngineType.VLLM
assert isinstance(options, VllmVlmEngineOptions), (
    f'options/engine_type mismatch: {type(options).__name__}'
)

from docling.datamodel.vlm_engine_options import VllmVlmEngineOptions

def is_vllm_options(opts: object) -> bool:
    return isinstance(opts, VllmVlmEngineOptions)

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 VllmVlmEngineOptions' in str(e):
        from docling.datamodel.vlm_engine_options import VllmVlmEngineOptions
        engine = create_vlm_engine(options=VllmVlmEngineOptions(), 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.VLLM while options is not VllmVlmEngineOptions (e.g. options built for the Transformers or API runtime).

Common situations: Switching from local Transformers inference to vLLM for throughput by editing only engine_type; deserialized config mapping to the wrong options class.

Related errors

• Expected AutoInlineVlmEngineOptions, got {type(options)}
• Expected TransformersVlmEngineOptions, got {type(options)}
• Expected MlxVlmEngineOptions, 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/622f3af022eb0440. Report an issue: GitHub.