docling-project/docling · error · ValueError

Unknown engine type: {options.engine_type}

Error message

Unknown engine type: {options.engine_type}

What it means

The object-detection engine factory ends with raise ValueError(f"Unknown engine type: {options.engine_type}") — reached only when the engine_type enum value is not one of ONNXRUNTIME, TRANSFORMERS, or API_KSERVE_V2. In practice this appears when a new/unknown enum value or a lookalike enum from another module is supplied.

Source

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

        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. Check ObjectDetectionEngineType members in your installed version and use one of the supported values.
2. Align docling and docling-core versions (reinstall in one resolved environment: uv/pip refresh) if the enum was extended.
3. If you need a custom engine, use the engine classes directly instead of extending the enum.

Example fix

# before
from my_custom_types import DetectionEngineType  # lookalike enum
opts.engine_type = DetectionEngineType.CUSTOM

# after
from docling.datamodel.object_detection_engine_options import ObjectDetectionEngineType
opts.engine_type = ObjectDetectionEngineType.ONNXRUNTIME  # supported value

supported = {e.value for e in ObjectDetectionEngineType}
assert opts.engine_type in supported, f"engine_type must be one of {supported}, got {opts.engine_type!r}"

try:
    engine = create_object_detection_engine(options=opts)
except ValueError as e:
    if "Unknown engine type" in str(e):
        log.error("Upgrade docling/docling-core together; supported: %s", list(ObjectDetectionEngineType))
    raise

When it happens

Trigger: Passing options whose engine_type is a member added by a newer Docling version than the installed one, or an enum imported from a different package that compares unequal to ObjectDetectionEngineType members.

Common situations: Version skew between docling packages (e.g. docling-core with extra enum members vs an older docling); monkey-patched or custom enum values injected for experimentation; stale .pyc/partial upgrades leaving mismatched enum definitions.

Related errors

• Unsupported engine type: {engine_type}
• Expected OnnxRuntimeImageClassificationEngineOptions, got {t
• Expected TransformersImageClassificationEngineOptions, got {
• Expected ApiKserveV2ImageClassificationEngineOptions, got {t
• Unknown engine type: {options.engine_type}

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