{"record":{"id":"ba05b4c1d1b62968","repo":"docling-project/docling","slug":"kserve-v2-client-is-not-initialized-ba05b4","errorCode":null,"errorMessage":"KServe v2 client is not initialized.","messagePattern":"KServe v2 client is not initialized\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/object_detection/api_kserve_v2_engine.py","lineNumber":76,"sourceCode":"\n        if not enable_remote_services:\n            raise OperationNotAllowed(\n                \"Connections to remote services are only allowed when set explicitly. \"\n                \"pipeline_options.enable_remote_services=True.\"\n            )\n\n    def _resolve_model_name(self) -> str:\n        if self.options.model_name:\n            return self.options.model_name\n\n        return self._repo_id.replace(\"/\", \"--\")\n\n    def _resolve_model_version(self) -> Optional[str]:\n        return self.options.model_version\n\n    def _resolve_tensor_names(self) -> tuple[str, str, str, str, str]:\n        if self._kserve_client is None:\n            raise RuntimeError(\"KServe v2 client is not initialized.\")\n\n        metadata = self._kserve_client.get_model_metadata()\n        if len(metadata.inputs) < 2:\n            raise RuntimeError(\n                \"Expected object-detection model metadata to expose at least 2 inputs \"\n                f\"(images, orig_target_sizes), got {len(metadata.inputs)}.\"\n            )\n        if len(metadata.outputs) < 3:\n            raise RuntimeError(\n                \"Expected object-detection model metadata to expose at least 3 outputs \"\n                f\"(labels, boxes, scores), got {len(metadata.outputs)}.\"\n            )\n\n        input_images_name = metadata.inputs[0].name\n        input_orig_target_sizes_name = metadata.inputs[1].name\n        output_labels_name = metadata.outputs[0].name\n        output_boxes_name = metadata.outputs[1].name\n        output_scores_name = metadata.outputs[2].name","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/object_detection/api_kserve_v2_engine.py#L58-L94","documentation":"The KServe v2 engine raises RuntimeError('KServe v2 client is not initialized.') in _resolve_tensor_names when self._kserve_client is still None. The tensor names for inputs/outputs are only discovered after the KServe V2 client is created during engine initialization, so calling any inference or metadata-dependent method before initialize() is a programming error.","triggerScenarios":"Instantiating ApiKserveV2ObjectDetectionEngine and calling predict_batch() (or anything that reaches _resolve_tensor_names) without calling engine.initialize() first; or initialize() having failed partway leaving the client unset while the exception was swallowed.","commonSituations":"Custom orchestration code that manages engine lifecycles manually and skips initialize(); a previous initialize() failure (bad URL, TLS error) being caught and ignored, then predict being attempted anyway.","solutions":["Call engine.initialize() once after construction and before predict_batch().","If initialize() was already called, check logs for an earlier swallowed exception during client construction (wrong url/inference_port in ApiKserveV2ObjectDetectionEngineOptions).","Do not catch and discard exceptions from initialize(); treat any initialization failure as fatal for that engine instance."],"exampleFix":"# before\nengine = ApiKserveV2ObjectDetectionEngine(options=opts, ...)\noutputs = engine.predict_batch(inputs)\n\n# after\nengine = ApiKserveV2ObjectDetectionEngine(options=opts, ...)\nengine.initialize()\noutputs = engine.predict_batch(inputs)","handlingStrategy":"validation","validationCode":"if engine._kserve_client is None:\n    engine.initialize()","typeGuard":null,"tryCatchPattern":"try:\n    engine.initialize()\nexcept Exception:\n    log.exception(\"KServe init failed; check url/port and network\")\n    raise","preventionTips":["Always pair construction with initialize() in the same code block.","Prefer the standard DocumentConverter pipeline over manual engine use.","Never swallow initialize() exceptions."],"tags":["lifecycle","kserve","initialization","object-detection"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}