docling-project/docling · error · ValueError

Expected OnnxRuntimeObjectDetectionEngineOptions, got {type(

Error message

Expected OnnxRuntimeObjectDetectionEngineOptions, got {type(options)}

What it means

The object-detection engine factory dispatches on options.engine_type. When engine_type is ONNXRUNTIME but the options object is not an OnnxRuntimeObjectDetectionEngineOptions instance, it raises ValueError. This catches inconsistent configuration where the enum tag and the options payload disagree.

Source

Thrown at docling/models/inference_engines/object_detection/factory.py:58

        artifacts_path: Optional path to local model artifacts root

    Returns:
        Initialized engine instance (call .initialize() before use)
    """
    model_config: Optional[EngineModelConfig] = None
    if model_spec is not None:
        model_config = model_spec.get_engine_config(options.engine_type)

    if options.engine_type == ObjectDetectionEngineType.ONNXRUNTIME:
        from docling.datamodel.object_detection_engine_options import (
            OnnxRuntimeObjectDetectionEngineOptions,
        )
        from docling.models.inference_engines.object_detection.onnxruntime_engine import (
            OnnxRuntimeObjectDetectionEngine,
        )

        if not isinstance(options, OnnxRuntimeObjectDetectionEngineOptions):
            raise ValueError(
                f"Expected OnnxRuntimeObjectDetectionEngineOptions, got {type(options)}"
            )

        return OnnxRuntimeObjectDetectionEngine(
            options=options,
            model_config=model_config,
            artifacts_path=artifacts_path,
            accelerator_options=accelerator_options,
        )

    elif options.engine_type == ObjectDetectionEngineType.TRANSFORMERS:
        from docling.datamodel.object_detection_engine_options import (
            TransformersObjectDetectionEngineOptions,
        )
        from docling.models.inference_engines.object_detection.transformers_engine import (
            TransformersObjectDetectionEngine,
        )

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Use OnnxRuntimeObjectDetectionEngineOptions as the options object — its default engine_type already selects ONNXRUNTIME.
2. If loading options from config files, deserialize into the concrete class matching the engine_type field.
3. Never assign engine_type on an options instance of a different engine family.

Example fix

# before
opts = ApiKserveV2ObjectDetectionEngineOptions(url=url)
opts.engine_type = ObjectDetectionEngineType.ONNXRUNTIME
engine = create_object_detection_engine(options=opts)

# after
from docling.datamodel.object_detection_engine_options import OnnxRuntimeObjectDetectionEngineOptions
opts = OnnxRuntimeObjectDetectionEngineOptions()
engine = create_object_detection_engine(options=opts)

from docling.datamodel.object_detection_engine_options import OnnxRuntimeObjectDetectionEngineOptions
assert isinstance(opts, OnnxRuntimeObjectDetectionEngineOptions), type(opts)

def is_onnx_opts(o: object) -> TypeGuard[OnnxRuntimeObjectDetectionEngineOptions]:
    return isinstance(o, OnnxRuntimeObjectDetectionEngineOptions)

try:
    engine = create_object_detection_engine(options=opts)
except ValueError as e:
    raise ConfigurationError(str(e)) from e  # surface config mismatch at startup

When it happens

Trigger: Setting options.engine_type = ObjectDetectionEngineType.ONNXRUNTIME on an options object of a different class (e.g. ApiKserveV2ObjectDetectionEngineOptions or a hand-built subclass), then calling the factory create function.

Common situations: Copy-pasting options classes and tweaking engine_type instead of using the right class; deserializing options from YAML/JSON into the wrong concrete type; mutating a shared options instance across pipelines.

Related errors

• Expected TransformersObjectDetectionEngineOptions, got {type
• Expected ApiKserveV2ObjectDetectionEngineOptions, got {type(
• Expected AutoInlineVlmEngineOptions, got {type(options)}
• Expected TransformersVlmEngineOptions, got {type(options)}
• Expected MlxVlmEngineOptions, got {type(options)}

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