{"record":{"id":"d9afd93d39c0aac9","repo":"docling-project/docling","slug":"engine-not-initialized-call-initialize-first-d9afd9","errorCode":null,"errorMessage":"Engine not initialized. Call initialize() first.","messagePattern":"Engine not initialized\\. Call initialize\\(\\) first\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/object_detection/api_kserve_v2_engine.py","lineNumber":173,"sourceCode":"\n        self._initialized = True\n        _log.info(\n            \"KServe v2 object-detection engine ready (inputs=[%s, %s], outputs=[%s, %s, %s])\",\n            self._input_images_name,\n            self._input_orig_target_sizes_name,\n            self._output_labels_name,\n            self._output_boxes_name,\n            self._output_scores_name,\n        )\n\n    def predict_batch(\n        self, input_batch: List[ObjectDetectionEngineInput]\n    ) -> List[ObjectDetectionEngineOutput]:\n        \"\"\"Run inference on a batch of images against a KServe v2 endpoint.\"\"\"\n        if not input_batch:\n            return []\n        if not self._initialized:\n            raise RuntimeError(\"Engine not initialized. Call initialize() first.\")\n\n        # Type narrowing: _initialized guarantees these are non-None\n        assert self._processor is not None\n        assert self._kserve_client is not None\n        assert self._input_images_name is not None\n        assert self._input_orig_target_sizes_name is not None\n        assert self._output_labels_name is not None\n        assert self._output_boxes_name is not None\n        assert self._output_scores_name is not None\n\n        if _log.isEnabledFor(logging.DEBUG):\n            _t_preproc_start = time.time()\n            _t_preproc_mono = time.monotonic()\n        images = [item.image.convert(\"RGB\") for item in input_batch]\n        processed_inputs = self._processor(images=images, return_tensors=\"np\")\n\n        pixel_values = np.asarray(processed_inputs[\"pixel_values\"])\n        orig_sizes = np.asarray(","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/object_detection/api_kserve_v2_engine.py#L155-L191","documentation":"predict_batch() on the KServe v2 engine raises RuntimeError when self._initialized is False. The engine performs expensive setup (HF processor download, KServe client construction, tensor-name discovery) in initialize(), and refuses to run inference before that completes.","triggerScenarios":"Calling engine.predict_batch(inputs) on a freshly constructed ApiKserveV2ObjectDetectionEngine without calling initialize(); or after initialize() raised and the caller ignored the failure.","commonSituations":"Manual engine lifecycle management in custom pipelines; retry wrappers that reconstruct the engine but skip initialization; async code paths where initialize() runs in another task that has not finished.","solutions":["Call engine.initialize() before predict_batch() (the standard pipeline does this for you — prefer using the pipeline API).","Guard with 'if not engine._initialized' style checks only internally; in application code simply always initialize right after construction.","Ensure initialize() exceptions propagate — never call predict after a failed init."],"exampleFix":"# before\nengine = ApiKserveV2ObjectDetectionEngine(options=opts, enable_remote_services=True)\nresults = engine.predict_batch(batch)\n\n# after\nengine = ApiKserveV2ObjectDetectionEngine(options=opts, enable_remote_services=True)\nengine.initialize()\nresults = engine.predict_batch(batch)","handlingStrategy":"validation","validationCode":"if not getattr(engine, \"_initialized\", False):\n    engine.initialize()\nassert engine._initialized","typeGuard":null,"tryCatchPattern":"try:\n    engine.predict_batch(batch)\nexcept RuntimeError as e:\n    if \"not initialized\" in str(e):\n        engine.initialize()\n        outputs = engine.predict_batch(batch)  # retry once after real init\n    else:\n        raise","preventionTips":["Wrap engine usage in a small context-manager that initializes on enter.","Use the pipeline API so lifecycle is handled for you.","Treat 'not initialized' as a code bug, not an environment issue."],"tags":["lifecycle","initialization","kserve","object-detection"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}