docling-project/docling · error · ValueError

Preset '{preset_id}' uses API_KSERVE_V2 engine which require

Error message

Preset '{preset_id}' uses API_KSERVE_V2 engine which requires explicit engine_options with a 'url' parameter. Please provide engine_options=ApiKserveV2ImageClassificationEngineOptions(url='...') when calling from_preset().

What it means

The image-classification analogue of the KServe guard: when ImageClassificationStage.from_preset() is called without engine_options and the preset's default engine is API_KSERVE_V2, construction fails because a KServe inference-server URL cannot be defaulted. You must supply engine_options with a url pointing at the KServe V2 endpoint.

Source

Thrown at docling/datamodel/stage_model_specs.py:893

            ApiKserveV2ImageClassificationEngineOptions,
            OnnxRuntimeImageClassificationEngineOptions,
            TransformersImageClassificationEngineOptions,
        )

        preset = cls.get_preset(preset_id)

        if engine_options is None:
            if preset.default_engine_type == ImageClassificationEngineType.ONNXRUNTIME:
                engine_options = OnnxRuntimeImageClassificationEngineOptions()
            elif (
                preset.default_engine_type == ImageClassificationEngineType.TRANSFORMERS
            ):
                engine_options = TransformersImageClassificationEngineOptions()
            elif (
                preset.default_engine_type
                == ImageClassificationEngineType.API_KSERVE_V2
            ):
                raise ValueError(
                    f"Preset '{preset_id}' uses API_KSERVE_V2 engine which requires explicit "
                    "engine_options with a 'url' parameter. Please provide "
                    "engine_options=ApiKserveV2ImageClassificationEngineOptions(url='...') "
                    "when calling from_preset()."
                )
            else:
                raise ValueError(
                    f"Unsupported engine type {preset.default_engine_type} for presets"
                )

        instance = cls(  # type: ignore[call-arg]
            model_spec=preset.model_spec,
            engine_options=engine_options,
            **preset.stage_options,
        )

        for key, value in overrides.items():
            setattr(instance, key, value)

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Pass engine_options=ApiKserveV2ImageClassificationEngineOptions(url='https://kserve-host/v2') to from_preset().
2. Prefer a local-engine preset (ONNXRUNTIME/TRANSFORMERS) if no remote server is available.
3. Centralize the KServe URL in settings/env so every call site supplies it.

Example fix

# before
stage = ImageClassificationStage.from_preset("remote_classifier")

# after
from docling.datamodel.image_classification_engine_options import ApiKserveV2ImageClassificationEngineOptions
stage = ImageClassificationStage.from_preset(
    "remote_classifier",
    engine_options=ApiKserveV2ImageClassificationEngineOptions(url="https://kserve.internal:8080"),
)

preset = ImageClassificationStage.get_preset(pid)
if preset.default_engine_type == ImageClassificationEngineType.API_KSERVE_V2 and engine_options is None:
    engine_options = ApiKserveV2ImageClassificationEngineOptions(url=KSERVE_URL)
stage = ImageClassificationStage.from_preset(pid, engine_options=engine_options)

def ic_needs_engine_options(preset_id: str) -> bool:
    return ImageClassificationStage.get_preset(preset_id).default_engine_type == ImageClassificationEngineType.API_KSERVE_V2

try:
    stage = ImageClassificationStage.from_preset(pid)
except ValueError as e:
    if "API_KSERVE_V2" in str(e):
        stage = ImageClassificationStage.from_preset(
            pid, engine_options=ApiKserveV2ImageClassificationEngineOptions(url=KSERVE_URL)
        )
    else:
        raise

When it happens

Trigger: ImageClassificationStage.from_preset('kserve-preset') with engine_options omitted, where the preset's default_engine_type is ImageClassificationEngineType.API_KSERVE_V2.

Common situations: Running classification presets designed for a hosted model server in an environment where the URL was expected to come from config; forgetting the URL when moving from local transformers to KServe deployment.

Related errors

• Preset '{preset_id}' uses API_KSERVE_V2 engine which require
• Preset '{preset_id}' not found for {cls.__name__}. Available
• Unsupported engine type {preset.default_engine_type} for pre
• Unsupported KServe request parameter integer range for gRPC:
• Unsupported KServe request parameter type for gRPC: key={key

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