docling-project/docling · error · ValueError

Expected OnnxRuntimeObjectDetectionEngineOptions, got

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.

Solutions

Use OnnxRuntimeObjectDetectionEngineOptions as the options object — its default engine_type already selects ONNXRUNTIME.
If loading options from config files, deserialize into the concrete class matching the engine_type field.
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)

Defensive patterns

Strategy: type-guard

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

Never reassign engine_type across option classes; construct the matching class.
Validate options type right after deserializing config files.
Keep one options class per engine family in your config schema.

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

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

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