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=ApiKserveV2ObjectDetectionEngineOptions(url='...') when calling from_preset().

What it means

When from_preset() is called on an object-detection stage without engine_options and the preset's default engine is API_KSERVE_V2 (a remote KServe V2 inference server), the code cannot construct default engine options because a server URL is mandatory. Local engines (ONNXRUNTIME, TRANSFORMERS) get default options, but KServe requires you to pass engine_options with a url explicitly.

Source

Thrown at docling/datamodel/stage_model_specs.py:778

        preset_id: str,
        engine_options: BaseObjectDetectionEngineOptions | None = None,
        **overrides: Any,
    ):
        from docling.datamodel.object_detection_engine_options import (
            ApiKserveV2ObjectDetectionEngineOptions,
            OnnxRuntimeObjectDetectionEngineOptions,
            TransformersObjectDetectionEngineOptions,
        )

        preset = cls.get_preset(preset_id)

        if engine_options is None:
            if preset.default_engine_type == ObjectDetectionEngineType.ONNXRUNTIME:
                engine_options = OnnxRuntimeObjectDetectionEngineOptions()
            elif preset.default_engine_type == ObjectDetectionEngineType.TRANSFORMERS:
                engine_options = TransformersObjectDetectionEngineOptions()
            elif preset.default_engine_type == ObjectDetectionEngineType.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=ApiKserveV2ObjectDetectionEngineOptions(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 explicitly: ObjectDetectionStage.from_preset(preset_id, engine_options=ApiKserveV2ObjectDetectionEngineOptions(url='https://kserve-host/v2')).
2. If you meant to run locally, choose a preset whose default engine is ONNXRUNTIME or TRANSFORMERS.
3. Load the KServe URL from environment/config so it is not hardcoded per call.

Example fix

# before
stage = ObjectDetectionStage.from_preset("remote_detector")

# after
from docling.datamodel.object_detection_engine_options import ApiKserveV2ObjectDetectionEngineOptions
stage = ObjectDetectionStage.from_preset(
    "remote_detector",
    engine_options=ApiKserveV2ObjectDetectionEngineOptions(url="https://kserve.internal:8080"),
)

preset = ObjectDetectionStage.get_preset(pid)
if preset.default_engine_type == ObjectDetectionEngineType.API_KSERVE_V2 and engine_options is None:
    engine_options = ApiKserveV2ObjectDetectionEngineOptions(url=KSERVE_URL)
stage = ObjectDetectionStage.from_preset(pid, engine_options=engine_options)

def needs_explicit_engine_options(stage_cls, preset_id: str) -> bool:
    p = stage_cls.get_preset(preset_id)
    return p.default_engine_type.value.endswith("API_KSERVE_V2")

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

When it happens

Trigger: ObjectDetectionStage.from_preset('some-kserve-preset') with no engine_options argument, where the preset's default_engine_type is ObjectDetectionEngineType.API_KSERVE_V2.

Common situations: Using a preset authored for a hosted/remote inference server while assuming local execution; deployments where models are served via KServe and the URL lives in config the caller forgot to wire through.

Related errors

• Preset '{preset_id}' uses API_KSERVE_V2 engine which require
• Unsupported engine type {preset.default_engine_type} for pre
• Connections to remote services are only allowed when set exp
• KServe v2 client is not initialized.
• Expected object-detection model metadata to expose at least

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