docling-project/docling · error · ValueError

Unsupported engine type: {engine_type}

Error message

Unsupported engine type: {engine_type}

What it means

create_vlm_engine is an exhaustive dispatcher over VlmEngineType: AUTO_INLINE, TRANSFORMERS, MLX, VLLM, and API variants are handled, and anything else falls through to this ValueError. It fires when options.engine_type is not a value the installed Docling version knows how to build an engine for.

Source

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

            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,
            model_config=model_config,
        )

    else:
        raise ValueError(f"Unsupported engine type: {engine_type}")

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Use one of the supported engine types: AUTO_INLINE, TRANSFORMERS, MLX, VLLM, or an API variant
2. Check for version skew: ensure only one docling version is imported (pip show docling / python -c 'import docling; print(docling.__version__)')
3. If you need a custom engine, subclass the options and engine but route through your own factory, not an unsupported enum value

Example fix

# before
from docling.models.inference_engines.vlm.base import VlmEngineType
class MyOptions(BaseVlmEngineOptions):
    engine_type: VlmEngineType = VlmEngineType('FUTURE_ENGINE')  # unsupported

# after
from docling.datamodel.vlm_engine_options import TransformersVlmEngineOptions
options = TransformersVlmEngineOptions()  # supported: AUTO_INLINE | TRANSFORMERS | MLX | VLLM | API

from docling.models.inference_engines.vlm.base import VlmEngineType, BaseVlmEngineOptions

SUPPORTED = {VlmEngineType.AUTO_INLINE, VlmEngineType.TRANSFORMERS, VlmEngineType.MLX, VlmEngineType.VLLM}

def engine_type_supported(opts: BaseVlmEngineOptions) -> bool:
    et = opts.engine_type
    return et in SUPPORTED or VlmEngineType.is_api_variant(et)

from docling.models.inference_engines.vlm.base import VlmEngineType, BaseVlmEngineOptions

def has_supported_engine_type(opts: BaseVlmEngineOptions) -> bool:
    et = opts.engine_type
    return et in (VlmEngineType.AUTO_INLINE, VlmEngineType.TRANSFORMERS, VlmEngineType.MLX, VlmEngineType.VLLM) or VlmEngineType.is_api_variant(et)

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 'Unsupported engine type' in str(e):
        raise SystemExit(f'Engine {options.engine_type!r} not supported by this docling build. Check for version skew.') from e
    raise

When it happens

Trigger: Calling create_vlm_engine with an engine_type enum member that is unknown to this Docling version (e.g. an enum value injected from a newer/older Docling, or a custom BaseVlmEngineOptions subclass whose engine_type returns a non-member value).

Common situations: Version skew: multiple Docling installations in the environment so options carry an enum from a different version; a custom options subclass overriding engine_type with an unsupported value; a typo'd or future engine type.

Related errors

• Unknown engine type: {options.engine_type}
• Expected AutoInlineVlmEngineOptions, got {type(options)}
• Expected TransformersVlmEngineOptions, got {type(options)}
• Expected MlxVlmEngineOptions, got {type(options)}
• Expected VllmVlmEngineOptions, got {type(options)}

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