{"record":{"id":"d084594b0bd11b66","repo":"docling-project/docling","slug":"engine-not-initialized-call-initialize-first-d08459","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/onnxruntime_engine.py","lineNumber":171,"sourceCode":"                device,\n            )\n        return [\"CPUExecutionProvider\"]\n\n    def predict_batch(\n        self, input_batch: List[ObjectDetectionEngineInput]\n    ) -> List[ObjectDetectionEngineOutput]:\n        \"\"\"Run inference on a batch of inputs.\n\n        Args:\n            input_batch: List of input images with metadata\n\n        Returns:\n            List of detection outputs\n        \"\"\"\n        if not input_batch:\n            return []\n        if self._session is None or self._processor is None:\n            raise RuntimeError(\"Engine not initialized. Call initialize() first.\")\n\n        # Preprocess images using HF processor (source of truth)\n        images = [item.image.convert(\"RGB\") for item in input_batch]\n        inputs = self._processor(images=images, return_tensors=\"np\")\n\n        # Get original sizes for post-processing\n        orig_sizes = np.array(\n            [[img.width, img.height] for img in images], dtype=np.int64\n        )\n\n        # Run ONNX inference\n        output_tensors = self._session.run(\n            None,\n            {\n                \"images\": inputs[\"pixel_values\"],\n                \"orig_target_sizes\": orig_sizes,\n            },\n        )","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/object_detection/onnxruntime_engine.py#L153-L189","documentation":"OnnxRuntimeObjectDetectionEngine.predict_batch() raises RuntimeError('Engine not initialized. Call initialize() first.') when self._session or self._processor is None. The ONNX InferenceSession and HF processor are created during initialize(), and inference is refused before both exist.","triggerScenarios":"Calling predict_batch() without a prior successful initialize(); or initialize() failed (missing model file, bad onnxruntime install) and the exception was swallowed before predict was attempted.","commonSituations":"Custom orchestration bypassing the standard pipeline; engine reuse after a crashed init; threading issues where one thread inits while another predicts.","solutions":["Call engine.initialize() immediately after construction and before any predict_batch().","Prefer the standard DocumentConverter pipeline, which manages engine initialization.","If init already ran, inspect earlier logs — the underlying failure (e.g. FileNotFoundError for the model) is the real problem."],"exampleFix":"# before\nengine = OnnxRuntimeObjectDetectionEngine(options=opts, ...)\nouts = engine.predict_batch(inputs)\n\n# after\nengine = OnnxRuntimeObjectDetectionEngine(options=opts, ...)\nengine.initialize()\nouts = engine.predict_batch(inputs)","handlingStrategy":"validation","validationCode":"if engine._session is None or engine._processor is None:\n    engine.initialize()","typeGuard":null,"tryCatchPattern":"try:\n    outs = engine.predict_batch(batch)\nexcept RuntimeError as e:\n    if \"not initialized\" in str(e):\n        engine.initialize()\n        outs = engine.predict_batch(batch)\n    else:\n        raise","preventionTips":["Call initialize() immediately after constructing any engine.","Use the pipeline API for automatic lifecycle handling.","Fail hard on init errors instead of continuing to predict."],"tags":["lifecycle","initialization","onnx","object-detection"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}