{"record":{"id":"0ac5306b3079a18a","repo":"docling-project/docling","slug":"expected-apikservev2imageclassificationengineoptio","errorCode":null,"errorMessage":"Expected ApiKserveV2ImageClassificationEngineOptions, got {type(options)}","messagePattern":"Expected ApiKserveV2ImageClassificationEngineOptions, got (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/image_classification/factory.py","lineNumber":86,"sourceCode":"            )\n\n        return TransformersImageClassificationEngine(\n            options=options,\n            model_config=model_config,\n            artifacts_path=artifacts_path,\n            accelerator_options=accelerator_options,\n        )\n\n    if options.engine_type == ImageClassificationEngineType.API_KSERVE_V2:\n        from docling.datamodel.image_classification_engine_options import (\n            ApiKserveV2ImageClassificationEngineOptions,\n        )\n        from docling.models.inference_engines.image_classification.api_kserve_v2_engine import (\n            ApiKserveV2ImageClassificationEngine,\n        )\n\n        if not isinstance(options, ApiKserveV2ImageClassificationEngineOptions):\n            raise ValueError(\n                \"Expected ApiKserveV2ImageClassificationEngineOptions, \"\n                f\"got {type(options)}\"\n            )\n\n        return ApiKserveV2ImageClassificationEngine(\n            enable_remote_services=enable_remote_services,\n            options=options,\n            model_config=model_config,\n            artifacts_path=artifacts_path,\n            accelerator_options=accelerator_options,\n        )\n\n    raise ValueError(f\"Unknown engine type: {options.engine_type}\")\n","sourceCodeStart":68,"sourceCodeEnd":100,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/image_classification/factory.py#L68-L100","documentation":"The factory validates that the API_KSERVE_V2 engine_type is paired with ApiKserveV2ImageClassificationEngineOptions. A mismatch means the caller declared the remote engine type but supplied options built for a different backend — the engine would then read remote-connection fields that do not exist on the wrong options class.","triggerScenarios":"Calling the factory with options.engine_type == ImageClassificationEngineType.API_KSERVE_V2 while options is not an ApiKserveV2ImageClassificationEngineOptions instance.","commonSituations":"Reusing a local-engine options object and flipping engine_type to API_KSERVE_V2; forgetting to switch the options class when moving from ONNX/Transformers to a remote KServe deployment; config-driven option construction with a stale class mapping.","solutions":["Create ApiKserveV2ImageClassificationEngineOptions (with inference_url etc.) instead of mutating another options object's engine_type.","Also set pipeline_options.enable_remote_services=True, since this engine requires the explicit opt-in.","Verify any config-to-options mapping keys off engine_type and instantiates the matching class."],"exampleFix":"# before\noptions = OnnxRuntimeImageClassificationEngineOptions()\noptions.engine_type = ImageClassificationEngineType.API_KSERVE_V2\n\n# after\nfrom docling.datamodel.image_classification_engine_options import ApiKserveV2ImageClassificationEngineOptions\noptions = ApiKserveV2ImageClassificationEngineOptions(inference_url=\"https://kserve.example/v2\")","handlingStrategy":"type-guard","validationCode":"from docling.datamodel.image_classification_engine_options import ApiKserveV2ImageClassificationEngineOptions\n\nif not isinstance(options, ApiKserveV2ImageClassificationEngineOptions):\n    raise TypeError(\"API_KSERVE_V2 requires ApiKserveV2ImageClassificationEngineOptions\")","typeGuard":"def is_kserve_options(options) -> TypeGuard[ApiKserveV2ImageClassificationEngineOptions]:\n    return isinstance(options, ApiKserveV2ImageClassificationEngineOptions)","tryCatchPattern":"try:\n    engine = create_engine(options=options, enable_remote_services=True, ...)\nexcept ValueError as e:\n    if \"Expected ApiKserveV2ImageClassificationEngineOptions\" in str(e):\n        options = ApiKserveV2ImageClassificationEngineOptions(inference_url=...)\n        engine = create_engine(options=options, enable_remote_services=True, ...)\n    else:\n        raise","preventionTips":["Construct remote-engine options with their required fields (inference_url) directly.","Pair the options-class check with the enable_remote_services flag check in one place.","Never mutate engine_type across backends; rebuild options instead."],"tags":["factory","options-mismatch","configuration","kserve"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}