{"record":{"id":"f8d204034f92fbd7","repo":"docling-project/docling","slug":"engine-not-initialized-call-initialize-first-f8d204","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/image_classification/onnxruntime_engine.py","lineNumber":166,"sourceCode":"            _log.warning(\n                \"Unsupported ONNX device '%s' for image classification. Falling back to CPU provider.\",\n                device,\n            )\n        return [\"CPUExecutionProvider\"]\n\n    def predict_batch(\n        self, input_batch: List[ImageClassificationEngineInput]\n    ) -> List[ImageClassificationEngineOutput]:\n        \"\"\"Run inference on a batch of inputs.\"\"\"\n        if not input_batch:\n            return []\n        if (\n            self._session is None\n            or self._processor is None\n            or self._input_name is None\n            or self._output_name is None\n        ):\n            raise RuntimeError(\"Engine not initialized. Call initialize() first.\")\n\n        images = [item.image.convert(\"RGB\") for item in input_batch]\n        inputs = self._processor(images=images, return_tensors=\"np\")\n        input_tensor = np.asarray(inputs[\"pixel_values\"], dtype=np.float32)\n\n        output_tensors = self._session.run(\n            [self._output_name],\n            {\n                self._input_name: input_tensor,\n            },\n        )\n\n        if len(output_tensors) < 1:\n            raise RuntimeError(\n                \"Expected ONNX model to return at least 1 output containing logits\"\n            )\n\n        logits_batch = np.asarray(output_tensors[0], dtype=np.float32)","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/image_classification/onnxruntime_engine.py#L148-L184","documentation":"predict_batch was called on the ONNX Runtime engine before initialize() completed. The guard checks that _session, _processor, _input_name, and _output_name are all set; any None means initialization never ran or failed partway, and inference would otherwise crash with an opaque AttributeError.","triggerScenarios":"Calling OnnxRuntimeImageClassificationEngine.predict_batch() when any of _session/_processor/_input_name/_output_name is None — initialize() skipped, failed (e.g. model file missing, graph invalid), or the engine was used after an init exception was suppressed.","commonSituations":"Retry wrappers that swallow initialize() failures and continue; custom pipelines that construct the engine but forget init; reusing an engine after an OOM or load failure cleared its session.","solutions":["Call engine.initialize() exactly once before the first predict_batch and let its errors propagate.","Diagnose any earlier initialize() failure (missing ONNX file, no graph inputs/outputs) instead of continuing past it.","Wrap engine usage in a lifecycle that guarantees init-then-predict ordering."],"exampleFix":"# before\nengine = OnnxRuntimeImageClassificationEngine(...)\nengine.predict_batch(batch)  # session is None\n\n# after\nengine = OnnxRuntimeImageClassificationEngine(...)\nengine.initialize()\nengine.predict_batch(batch)","handlingStrategy":"validation","validationCode":"if any(getattr(engine, attr, None) is None for attr in (\"_session\", \"_processor\", \"_input_name\", \"_output_name\")):\n    engine.initialize()","typeGuard":null,"tryCatchPattern":"try:\n    engine.predict_batch(batch)\nexcept RuntimeError as e:\n    if \"not initialized\" in str(e):\n        engine.initialize()\n        engine.predict_batch(batch)\n    else:\n        raise","preventionTips":["Guarantee init-before-predict with a wrapper or context manager.","Treat initialize() exceptions as fatal; never continue with a partially initialized engine.","Rebuild the engine after session-level failures."],"tags":["lifecycle","initialization","onnx","call-order"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}