docling-project/docling · error · ValueError

Expected ApiKserveV2ObjectDetectionEngineOptions, got {type(

Error message

Expected ApiKserveV2ObjectDetectionEngineOptions, got {type(options)}

What it means

The factory raises ValueError when engine_type is API_KSERVE_V2 but options is not an ApiKserveV2ObjectDetectionEngineOptions instance. Because the KServe engine makes remote calls, the factory also threads enable_remote_services through, and an options/type mismatch means configuration integrity is broken.

Source

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

            )

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

    elif options.engine_type == ObjectDetectionEngineType.API_KSERVE_V2:
        from docling.datamodel.object_detection_engine_options import (
            ApiKserveV2ObjectDetectionEngineOptions,
        )
        from docling.models.inference_engines.object_detection.api_kserve_v2_engine import (
            ApiKserveV2ObjectDetectionEngine,
        )

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

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

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

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Use ApiKserveV2ObjectDetectionEngineOptions (with url and related fields) as the options object.
2. Pass enable_remote_services=True from the pipeline options so the constructed engine does not immediately raise OperationNotAllowed.
3. Rebuild config from the Docling examples for the KServe path rather than patching an existing ONNX/Transformers config.

Example fix

# before
opts = OnnxRuntimeObjectDetectionEngineOptions()
opts.engine_type = ObjectDetectionEngineType.API_KSERVE_V2

# after
from docling.datamodel.object_detection_engine_options import ApiKserveV2ObjectDetectionEngineOptions
opts = ApiKserveV2ObjectDetectionEngineOptions(url="https://kserve.example.com")

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

def is_kserve_opts(o: object) -> TypeGuard[ApiKserveV2ObjectDetectionEngineOptions]:
    return isinstance(o, ApiKserveV2ObjectDetectionEngineOptions)

try:
    engine = create_object_detection_engine(options=opts, enable_remote_services=True)
except ValueError as e:
    raise ConfigurationError(str(e)) from e

When it happens

Trigger: Setting engine_type = ObjectDetectionEngineType.API_KSERVE_V2 on options of another concrete class and calling the factory's create function.

Common situations: Adapting a local-engine config to a remote KServe setup by only changing the enum; deserializing persisted options with a schema that lost the concrete class; sharing one options dict across multiple engine types.

Related errors

• Expected OnnxRuntimeObjectDetectionEngineOptions, got {type(
• Expected TransformersObjectDetectionEngineOptions, got {type
• Expected ApiKserveV2ImageClassificationEngineOptions, got {t
• Connections to remote services are only allowed when set exp
• Expected AutoInlineVlmEngineOptions, got {type(options)}

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