docling-project/docling · error · ValueError

Expected ApiKserveV2ImageClassificationEngineOptions, got {t

Error message

Expected ApiKserveV2ImageClassificationEngineOptions, got {type(options)}

What it means

The factory validates that the API_KSERVE_V2 engine_type is paired with ApiKserveV2ImageClassificationEngineOptions. A mismatch means the caller declared the remote engine type but supplied options built for a different backend — the engine would then read remote-connection fields that do not exist on the wrong options class.

Source

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

            )

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

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

        return ApiKserveV2ImageClassificationEngine(
            enable_remote_services=enable_remote_services,
            options=options,
            model_config=model_config,
            artifacts_path=artifacts_path,
            accelerator_options=accelerator_options,
        )

    raise ValueError(f"Unknown engine type: {options.engine_type}")

View on GitHub (pinned to 61d76f1ff3)

Solutions

Create ApiKserveV2ImageClassificationEngineOptions (with inference_url etc.) instead of mutating another options object's engine_type.
Also set pipeline_options.enable_remote_services=True, since this engine requires the explicit opt-in.
Verify any config-to-options mapping keys off engine_type and instantiates the matching class.

Example fix

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

# after
from docling.datamodel.image_classification_engine_options import ApiKserveV2ImageClassificationEngineOptions
options = ApiKserveV2ImageClassificationEngineOptions(inference_url="https://kserve.example/v2")

Defensive patterns

Strategy: type-guard

Validate before calling

from docling.datamodel.image_classification_engine_options import ApiKserveV2ImageClassificationEngineOptions

if not isinstance(options, ApiKserveV2ImageClassificationEngineOptions):
    raise TypeError("API_KSERVE_V2 requires ApiKserveV2ImageClassificationEngineOptions")

Type guard

def is_kserve_options(options) -> TypeGuard[ApiKserveV2ImageClassificationEngineOptions]:
    return isinstance(options, ApiKserveV2ImageClassificationEngineOptions)

Try / catch

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

Prevention

Construct remote-engine options with their required fields (inference_url) directly.
Pair the options-class check with the enable_remote_services flag check in one place.
Never mutate engine_type across backends; rebuild options instead.

When it happens

Trigger: Calling the factory with options.engine_type == ImageClassificationEngineType.API_KSERVE_V2 while options is not an ApiKserveV2ImageClassificationEngineOptions instance.

Common situations: Reusing a local-engine options object and flipping engine_type to API_KSERVE_V2; forgetting to switch the options class when moving from ONNX/Transformers to a remote KServe deployment; config-driven option construction with a stale class mapping.

Related errors

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