docling-project/docling · error · ValueError

Expected AutoInlineVlmEngineOptions, got {type(options)}

Error message

Expected AutoInlineVlmEngineOptions, got {type(options)}

What it means

create_vlm_engine dispatches on options.engine_type and requires the options object class to match the engine type. For VlmEngineType.AUTO_INLINE it demands an AutoInlineVlmEngineOptions instance; any other options subclass raises this ValueError. This guards against mixing an engine type with options meant for a different runtime.

Source

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

    # Generate model_config from model_spec if provided
    model_config: Optional[EngineModelConfig] = None
    if model_spec is not None and engine_type != VlmEngineType.AUTO_INLINE:
        # AUTO_INLINE handles model_spec internally
        model_config = model_spec.get_engine_config(engine_type)

        # For API engines, add API params to extra_config
        if VlmEngineType.is_api_variant(engine_type):
            api_params = model_spec.get_api_params(engine_type)
            model_config.extra_config["api_params"] = api_params

    if engine_type == VlmEngineType.AUTO_INLINE:
        from docling.datamodel.vlm_engine_options import AutoInlineVlmEngineOptions
        from docling.models.inference_engines.vlm.auto_inline_engine import (
            AutoInlineVlmEngine,
        )

        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)}"

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Pass AutoInlineVlmEngineOptions when engine_type is AUTO_INLINE
2. If you meant a different runtime, keep the options class and set its matching engine_type instead
3. Check that the options class and engine_type come from the same construction site in your config code

Example fix

# before
options = ApiVlmEngineOptions(engine_type=VlmEngineType.AUTO_INLINE)
engine = create_vlm_engine(options=options, ...)

# after
from docling.datamodel.vlm_engine_options import AutoInlineVlmEngineOptions
options = AutoInlineVlmEngineOptions()  # engine_type is AUTO_INLINE by default
engine = create_vlm_engine(options=options, ...)

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

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

from docling.datamodel.vlm_engine_options import AutoInlineVlmEngineOptions

def is_auto_inline_options(opts: object) -> bool:
    return isinstance(opts, AutoInlineVlmEngineOptions)

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 AutoInlineVlmEngineOptions' in str(e):
        # fix the options class and retry once
        from docling.datamodel.vlm_engine_options import AutoInlineVlmEngineOptions
        engine = create_vlm_engine(options=AutoInlineVlmEngineOptions(), model_spec=spec, enable_remote_services=False, artifacts_path=None, accelerator_options=acc)
    else:
        raise

When it happens

Trigger: Calling create_vlm_engine(options=..., model_spec=...) where options.engine_type == VlmEngineType.AUTO_INLINE but options is e.g. ApiVlmEngineOptions, TransformersVlmEngineOptions, or a hand-rolled BaseVlmEngineOptions subclass.

Common situations: Copy-pasting a pipeline config and changing only the engine_type string while keeping the old options class; passing a generic options object because the config loader did not map the type correctly.

Related errors

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