docling-project/docling · error · ValueError

Unknown engine type: {options.engine_type}

Error message

Unknown engine type: {options.engine_type}

What it means

The image-classification engine factory fell through all known engine-type branches (ONNXRUNTIME, TRANSFORMERS, API_KSERVE_V2) and hit the terminal raise. The options.engine_type value is not a member the factory recognizes — typically an invalid string, a new enum member added without factory support, or None.

Source

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

        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

  1. Set engine_type to a valid ImageClassificationEngineType member (e.g. ONNXRUNTIME, TRANSFORMERS, or API_KSERVE_V2) via the matching options class.
  2. If the value comes from config, validate it against ImageClassificationEngineType before building options (e.g. ImageClassificationEngineType(value)).
  3. If you need an engine type you believe exists, check that your installed docling version's factory supports it and upgrade/downgrade accordingly.

Example fix

# before
options.engine_type = "onnx"  # not a valid enum value

# after
from docling.datamodel.image_classification_engine_options import OnnxRuntimeImageClassificationEngineOptions
options = OnnxRuntimeImageClassificationEngineOptions()  # engine_type correct by construction
Defensive patterns

Strategy: validation

Validate before calling

from docling.datamodel.image_classification_engine_options import ImageClassificationEngineType

engine_type = ImageClassificationEngineType(options.engine_type)  # raises ValueError on invalid values

Type guard

def is_known_engine_type(value) -> bool:
    try:
        ImageClassificationEngineType(value)
        return True
    except ValueError:
        return False

Try / catch

try:
    engine = create_engine(options=options, ...)
except ValueError as e:
    if "Unknown engine type" in str(e):
        raise SystemExit(f"unsupported engine_type {options.engine_type!r}; valid: "
                         f"{[t.value for t in ImageClassificationEngineType]}") from e
    raise

Prevention

When it happens

Trigger: Calling create_image_classification_engine-style factory functions with options.engine_type set to something outside the handled ImageClassificationEngineType members (or an engine_type injected as a raw string that equals none of them).

Common situations: Typo in a config-provided engine type; constructing options manually with an unvalidated string; using a newer/older docling version where the enum and factory branches are out of sync; engine_type left as an unsupported default.

Related errors

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