{"record":{"id":"d42f4dd61b94da98","repo":"docling-project/docling","slug":"preset-preset-id-uses-api-kserve-v2-engine-whi-d42f4d","errorCode":null,"errorMessage":"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().","messagePattern":"Preset '(.+?)' uses API_KSERVE_V2 engine which requires explicit engine_options with a 'url' parameter\\. Please provide engine_options=ApiKserveV2ImageClassificationEngineOptions\\(url='\\.\\.\\.'\\) when calling from_preset\\(\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/datamodel/stage_model_specs.py","lineNumber":893,"sourceCode":"            ApiKserveV2ImageClassificationEngineOptions,\n            OnnxRuntimeImageClassificationEngineOptions,\n            TransformersImageClassificationEngineOptions,\n        )\n\n        preset = cls.get_preset(preset_id)\n\n        if engine_options is None:\n            if preset.default_engine_type == ImageClassificationEngineType.ONNXRUNTIME:\n                engine_options = OnnxRuntimeImageClassificationEngineOptions()\n            elif (\n                preset.default_engine_type == ImageClassificationEngineType.TRANSFORMERS\n            ):\n                engine_options = TransformersImageClassificationEngineOptions()\n            elif (\n                preset.default_engine_type\n                == ImageClassificationEngineType.API_KSERVE_V2\n            ):\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=ApiKserveV2ImageClassificationEngineOptions(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":875,"sourceCodeEnd":911,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/datamodel/stage_model_specs.py#L875-L911","documentation":"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.","triggerScenarios":"ImageClassificationStage.from_preset('kserve-preset') with engine_options omitted, where the preset's default_engine_type is ImageClassificationEngineType.API_KSERVE_V2.","commonSituations":"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.","solutions":["Pass engine_options=ApiKserveV2ImageClassificationEngineOptions(url='https://kserve-host/v2') to from_preset().","Prefer a local-engine preset (ONNXRUNTIME/TRANSFORMERS) if no remote server is available.","Centralize the KServe URL in settings/env so every call site supplies it."],"exampleFix":"# before\nstage = ImageClassificationStage.from_preset(\"remote_classifier\")\n\n# after\nfrom docling.datamodel.image_classification_engine_options import ApiKserveV2ImageClassificationEngineOptions\nstage = ImageClassificationStage.from_preset(\n    \"remote_classifier\",\n    engine_options=ApiKserveV2ImageClassificationEngineOptions(url=\"https://kserve.internal:8080\"),\n)","handlingStrategy":"validation","validationCode":"preset = ImageClassificationStage.get_preset(pid)\nif preset.default_engine_type == ImageClassificationEngineType.API_KSERVE_V2 and engine_options is None:\n    engine_options = ApiKserveV2ImageClassificationEngineOptions(url=KSERVE_URL)\nstage = ImageClassificationStage.from_preset(pid, engine_options=engine_options)","typeGuard":"def ic_needs_engine_options(preset_id: str) -> bool:\n    return ImageClassificationStage.get_preset(preset_id).default_engine_type == ImageClassificationEngineType.API_KSERVE_V2","tryCatchPattern":"try:\n    stage = ImageClassificationStage.from_preset(pid)\nexcept ValueError as e:\n    if \"API_KSERVE_V2\" in str(e):\n        stage = ImageClassificationStage.from_preset(\n            pid, engine_options=ApiKserveV2ImageClassificationEngineOptions(url=KSERVE_URL)\n        )\n    else:\n        raise","preventionTips":["Wrap from_preset for KServe presets in a factory that always injects the URL.","Fail fast at startup if a KServe URL is configured but unreachable."],"tags":["kserve","inference-server","engine-options","preset","image-classification"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}