docling-project/docling · error · ValueError

Expected VllmVlmEngineOptions, got

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.

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 ApiVlmEngineOptions, got
• Expected AutoInlineVlmEngineOptions, got
• Expected MlxVlmEngineOptions, got
• Expected TransformersVlmEngineOptions, got
• Expected ApiKserveV2ObjectDetectionEngineOptions, got

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

Appendix: 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)