docling-project/docling · error · ValueError

Expected TransformersVlmEngineOptions, got {type(options)}

Error message

Expected TransformersVlmEngineOptions, got {type(options)}

What it means

create_vlm_engine requires the options class to match the requested engine type. For VlmEngineType.TRANSFORMERS it demands a TransformersVlmEngineOptions instance; anything else raises this ValueError before the engine is constructed.

Source

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

        if not isinstance(options, AutoInlineVlmEngineOptions):
            raise ValueError(
                f"Expected AutoInlineVlmEngineOptions, got {type(options)}"
            )
        return AutoInlineVlmEngine(
            options,
            model_spec=model_spec,
            artifacts_path=artifacts_path,
            accelerator_options=accelerator_options,
        )

    elif engine_type == VlmEngineType.TRANSFORMERS:
        from docling.datamodel.vlm_engine_options import TransformersVlmEngineOptions
        from docling.models.inference_engines.vlm.transformers_engine import (
            TransformersVlmEngine,
        )

        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
        )

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Use TransformersVlmEngineOptions (which carries device, dtype, prompts, and transformers-specific knobs) for the TRANSFORMERS engine type
2. If you intended another runtime, revert engine_type to match the options class you already have
3. Ensure YAML/JSON config loaders instantiate the options class corresponding to the engine_type field

Example fix

# before
options = VllmVlmEngineOptions(engine_type=VlmEngineType.TRANSFORMERS)
engine = create_vlm_engine(options=options, ...)

# after
from docling.datamodel.vlm_engine_options import TransformersVlmEngineOptions
options = TransformersVlmEngineOptions()  # engine_type defaults to TRANSFORMERS
engine = create_vlm_engine(options=options, ...)

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

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

from docling.datamodel.vlm_engine_options import TransformersVlmEngineOptions

def is_transformers_options(opts: object) -> bool:
    return isinstance(opts, TransformersVlmEngineOptions)

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 TransformersVlmEngineOptions' in str(e):
        from docling.datamodel.vlm_engine_options import TransformersVlmEngineOptions
        engine = create_vlm_engine(options=TransformersVlmEngineOptions(), 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.TRANSFORMERS while options is not TransformersVlmEngineOptions (e.g. VllmVlmEngineOptions or AutoInlineVlmEngineOptions).

Common situations: Switching a pipeline from vLLM or MLX to the Transformers engine by editing only the engine_type enum; config deserialization producing the wrong options subclass.

Related errors

• Expected AutoInlineVlmEngineOptions, got {type(options)}
• Expected MlxVlmEngineOptions, got {type(options)}
• Expected VllmVlmEngineOptions, got {type(options)}
• Expected ApiVlmEngineOptions, got {type(options)}
• Expected TransformersImageClassificationEngineOptions, got {

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