docling-project/docling · error · ValueError

Expected TransformersImageClassificationEngineOptions, got {

Error message

Expected TransformersImageClassificationEngineOptions, got {type(options)}

What it means

The engine factory requires that a TRANSFORMERS engine_type be paired with a TransformersImageClassificationEngineOptions instance. The isinstance check fails when the options object's concrete class does not match the declared engine_type, which almost always means engine_type was set independently of the options class.

Source

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

            )

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

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

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

    if options.engine_type == ImageClassificationEngineType.API_KSERVE_V2:
        from docling.datamodel.image_classification_engine_options import (
            ApiKserveV2ImageClassificationEngineOptions,
        )
        from docling.models.inference_engines.image_classification.api_kserve_v2_engine import (
            ApiKserveV2ImageClassificationEngine,
        )

View on GitHub (pinned to 61d76f1ff3)

Solutions

Instantiate TransformersImageClassificationEngineOptions directly instead of mutating another engine's options.
When loading options from configuration, map the engine_type string to the corresponding options class before calling the factory.
Remove any code that assigns engine_type on an existing options instance.

Example fix

# before
options = OnnxRuntimeImageClassificationEngineOptions()
options.engine_type = ImageClassificationEngineType.TRANSFORMERS

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

Defensive patterns

Strategy: type-guard

Validate before calling

from docling.datamodel.image_classification_engine_options import TransformersImageClassificationEngineOptions

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

Type guard

def is_transformers_options(options) -> TypeGuard[TransformersImageClassificationEngineOptions]:
    return isinstance(options, TransformersImageClassificationEngineOptions)

Try / catch

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

Prevention

Map each engine type to its options class in one lookup used by all config loading.
Reject configs that specify engine_type separately from the options class.
Add unit tests asserting factory + options class pairings.

When it happens

Trigger: Calling the factory with options.engine_type == ImageClassificationEngineType.TRANSFORMERS but options is not a TransformersImageClassificationEngineOptions (e.g. an ONNX options object with engine_type reassigned, or a plain/base options object).

Common situations: Programmatically switching backends by mutating engine_type on a shared options object; deserializing options from dict/JSON into the wrong class; partial migration when adopting the engine-options refactor.

Related errors

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