docling-project/docling · error · ValueError

Expected OnnxRuntimeImageClassificationEngineOptions, got {t

Error message

Expected OnnxRuntimeImageClassificationEngineOptions, got {type(options)}

What it means

The image-classification engine factory dispatches on options.engine_type, and for EngineType.ONNXRUNTIME the options object must be OnnxRuntimeImageClassificationEngineOptions. Passing an options instance belonging to a different engine (with engine_type=ONNXRUNTIME) indicates inconsistent construction — usually engine_type was mutated after the options object was created.

Source

Thrown at docling/models/inference_engines/image_classification/factory.py:44

    enable_remote_services: bool = False,
    accelerator_options: AcceleratorOptions,
    artifacts_path: Optional[Union[Path, str]] = None,
) -> BaseImageClassificationEngine:
    """Factory to create image-classification engines."""
    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 == ImageClassificationEngineType.ONNXRUNTIME:
        from docling.datamodel.image_classification_engine_options import (
            OnnxRuntimeImageClassificationEngineOptions,
        )
        from docling.models.inference_engines.image_classification.onnxruntime_engine import (
            OnnxRuntimeImageClassificationEngine,
        )

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

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

    if options.engine_type == ImageClassificationEngineType.TRANSFORMERS:
        from docling.datamodel.image_classification_engine_options import (
            TransformersImageClassificationEngineOptions,
        )
        from docling.models.inference_engines.image_classification.transformers_engine import (
            TransformersImageClassificationEngine,
        )

View on GitHub (pinned to 61d76f1ff3)

Solutions

Construct the matching options class: OnnxRuntimeImageClassificationEngineOptions() — its engine_type is already correct; do not override engine_type manually.
If building options from a model spec/config, make sure get_engine_config returns the class tied to the declared engine_type.
Audit code for assignments like options.engine_type = ... and replace them with instantiation of the proper options subclass.

Example fix

# before
options = TransformersImageClassificationEngineOptions()
options.engine_type = ImageClassificationEngineType.ONNXRUNTIME  # mismatch

# after
from docling.datamodel.image_classification_engine_options import OnnxRuntimeImageClassificationEngineOptions
options = OnnxRuntimeImageClassificationEngineOptions()

Defensive patterns

Strategy: type-guard

Validate before calling

from docling.datamodel.image_classification_engine_options import OnnxRuntimeImageClassificationEngineOptions

if not isinstance(options, OnnxRuntimeImageClassificationEngineOptions):
    options = OnnxRuntimeImageClassificationEngineOptions(**options.model_dump())

Type guard

def is_onnx_options(options) -> TypeGuard[OnnxRuntimeImageClassificationEngineOptions]:
    return isinstance(options, OnnxRuntimeImageClassificationEngineOptions)

Try / catch

try:
    engine = create_engine(options=options, ...)
except ValueError as e:
    if "Expected OnnxRuntimeImageClassificationEngineOptions" in str(e):
        options = OnnxRuntimeImageClassificationEngineOptions()
        engine = create_engine(options=options, ...)
    else:
        raise

Prevention

Never assign engine_type on an existing options object; instantiate the right class.
Use TypeGuard checks before factory calls when options arrive from dynamic config.
Derive engine_type from the options instance rather than a separate field.

When it happens

Trigger: Calling the factory's create function with options whose .engine_type == ImageClassificationEngineType.ONNXRUNTIME but whose concrete class is not OnnxRuntimeImageClassificationEngineOptions — e.g. manually setting engine_type on a Transformers options object.

Common situations: Copying a base/default options object and flipping only the engine_type field; config files deserialized into a generic options class with a stale engine_type; mixing option classes during a migration between engine backends.

Related errors

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