{"record":{"id":"000e780e925a8b04","repo":"docling-project/docling","slug":"preset-preset-id-uses-api-kserve-v2-engine-whi","errorCode":null,"errorMessage":"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().","messagePattern":"Preset '(.+?)' uses API_KSERVE_V2 engine which requires explicit engine_options with a 'url' parameter\\. Please provide engine_options=ApiKserveV2ObjectDetectionEngineOptions\\(url='\\.\\.\\.'\\) when calling from_preset\\(\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/datamodel/stage_model_specs.py","lineNumber":778,"sourceCode":"        preset_id: str,\n        engine_options: BaseObjectDetectionEngineOptions | None = None,\n        **overrides: Any,\n    ):\n        from docling.datamodel.object_detection_engine_options import (\n            ApiKserveV2ObjectDetectionEngineOptions,\n            OnnxRuntimeObjectDetectionEngineOptions,\n            TransformersObjectDetectionEngineOptions,\n        )\n\n        preset = cls.get_preset(preset_id)\n\n        if engine_options is None:\n            if preset.default_engine_type == ObjectDetectionEngineType.ONNXRUNTIME:\n                engine_options = OnnxRuntimeObjectDetectionEngineOptions()\n            elif preset.default_engine_type == ObjectDetectionEngineType.TRANSFORMERS:\n                engine_options = TransformersObjectDetectionEngineOptions()\n            elif preset.default_engine_type == ObjectDetectionEngineType.API_KSERVE_V2:\n                raise ValueError(\n                    f\"Preset '{preset_id}' uses API_KSERVE_V2 engine which requires explicit \"\n                    \"engine_options with a 'url' parameter. Please provide \"\n                    \"engine_options=ApiKserveV2ObjectDetectionEngineOptions(url='...') \"\n                    \"when calling from_preset().\"\n                )\n            else:\n                raise ValueError(\n                    f\"Unsupported engine type {preset.default_engine_type} for presets\"\n                )\n\n        instance = cls(  # type: ignore[call-arg]\n            model_spec=preset.model_spec,\n            engine_options=engine_options,\n            **preset.stage_options,\n        )\n\n        for key, value in overrides.items():\n            setattr(instance, key, value)","sourceCodeStart":760,"sourceCodeEnd":796,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/datamodel/stage_model_specs.py#L760-L796","documentation":"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.","triggerScenarios":"ObjectDetectionStage.from_preset('some-kserve-preset') with no engine_options argument, where the preset's default_engine_type is ObjectDetectionEngineType.API_KSERVE_V2.","commonSituations":"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.","solutions":["Pass engine_options explicitly: ObjectDetectionStage.from_preset(preset_id, engine_options=ApiKserveV2ObjectDetectionEngineOptions(url='https://kserve-host/v2')).","If you meant to run locally, choose a preset whose default engine is ONNXRUNTIME or TRANSFORMERS.","Load the KServe URL from environment/config so it is not hardcoded per call."],"exampleFix":"# before\nstage = ObjectDetectionStage.from_preset(\"remote_detector\")\n\n# after\nfrom docling.datamodel.object_detection_engine_options import ApiKserveV2ObjectDetectionEngineOptions\nstage = ObjectDetectionStage.from_preset(\n    \"remote_detector\",\n    engine_options=ApiKserveV2ObjectDetectionEngineOptions(url=\"https://kserve.internal:8080\"),\n)","handlingStrategy":"validation","validationCode":"preset = ObjectDetectionStage.get_preset(pid)\nif preset.default_engine_type == ObjectDetectionEngineType.API_KSERVE_V2 and engine_options is None:\n    engine_options = ApiKserveV2ObjectDetectionEngineOptions(url=KSERVE_URL)\nstage = ObjectDetectionStage.from_preset(pid, engine_options=engine_options)","typeGuard":"def needs_explicit_engine_options(stage_cls, preset_id: str) -> bool:\n    p = stage_cls.get_preset(preset_id)\n    return p.default_engine_type.value.endswith(\"API_KSERVE_V2\")","tryCatchPattern":"try:\n    stage = ObjectDetectionStage.from_preset(pid)\nexcept ValueError as e:\n    if \"API_KSERVE_V2\" in str(e):\n        stage = ObjectDetectionStage.from_preset(\n            pid, engine_options=ApiKserveV2ObjectDetectionEngineOptions(url=KSERVE_URL)\n        )\n    else:\n        raise","preventionTips":["Always pass engine_options for remote-engine presets; never rely on defaults for KServe.","Keep the KServe endpoint URL in central settings so call sites cannot forget it."],"tags":["kserve","inference-server","engine-options","preset","object-detection"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}