docling-project/docling · error · ValueError

Expected TransformersObjectDetectionEngineOptions, got {type

Error message

Expected TransformersObjectDetectionEngineOptions, got {type(options)}

What it means

The factory raises ValueError when options.engine_type is TRANSFORMERS but the options object is not a TransformersObjectDetectionEngineOptions instance. Each engine_type branch validates the concrete options type so that downstream engines receive the fields they expect.

Source

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

            )

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

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

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

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Construct TransformersObjectDetectionEngineOptions directly — it carries the correct engine_type by default.
2. When changing engine families in a config, replace the whole options object, not just the engine_type field.
3. Add a startup assertion that type(options) matches the expected class per engine_type.

Example fix

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

# after
from docling.datamodel.object_detection_engine_options import TransformersObjectDetectionEngineOptions
opts = TransformersObjectDetectionEngineOptions()

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

def is_transformers_opts(o: object) -> TypeGuard[TransformersObjectDetectionEngineOptions]:
    return isinstance(o, TransformersObjectDetectionEngineOptions)

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

When it happens

Trigger: Setting engine_type = ObjectDetectionEngineType.TRANSFORMERS on a non-Transformers options object (ONNX or KServe options class) and invoking the factory.

Common situations: Switching engines by flipping only the engine_type enum in an existing config; YAML-driven pipelines where the options class mapping is out of sync with the enum; refactors that changed option class names.

Related errors

• Expected OnnxRuntimeObjectDetectionEngineOptions, got {type(
• Expected ApiKserveV2ObjectDetectionEngineOptions, got {type(
• Expected AutoInlineVlmEngineOptions, got {type(options)}
• Expected TransformersVlmEngineOptions, got {type(options)}
• Expected MlxVlmEngineOptions, got {type(options)}

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