{"record":{"id":"5e70b4d870dcbef3","repo":"docling-project/docling","slug":"engine-not-initialized","errorCode":null,"errorMessage":"Engine not initialized","messagePattern":"Engine not initialized","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/models/stages/code_formula/code_formula_vlm_model.py","lineNumber":241,"sourceCode":"        doc: DoclingDocument,\n        element_batch: Iterable[ItemAndImageEnrichmentElement],\n    ) -> Iterable[NodeItem]:\n        \"\"\"Process a batch of code/formula elements.\n\n        Args:\n            doc: The document being processed\n            element_batch: Batch of elements to process\n\n        Yields:\n            Enriched elements with extracted text\n        \"\"\"\n        if not self.enabled:\n            for element in element_batch:\n                yield element.item\n            return\n\n        if self.engine is None:\n            raise RuntimeError(\"Engine not initialized\")\n\n        labels: List[str] = []\n        images: List[Union[Image.Image, np.ndarray]] = []\n        elements: List[Union[CodeItem, TextItem]] = []\n\n        for el in element_batch:\n            assert isinstance(el.item, CodeItem | TextItem)\n            elements.append(el.item)\n            labels.append(el.item.label)\n            images.append(el.image)\n\n        # Process batch through engine\n        try:\n            # Prepare batch of engine inputs\n            engine_inputs = [\n                VlmEngineInput(\n                    image=image\n                    if isinstance(image, Image.Image)","sourceCodeStart":223,"sourceCodeEnd":259,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/stages/code_formula/code_formula_vlm_model.py#L223-L259","documentation":"The VLM code/formula stage requires a loaded inference engine; it stores it on self.engine during initialization. If __call__ runs with self.engine still None — typically because the model was constructed with enabled=False and later called directly, or initialization failed/was skipped — this RuntimeError aborts batch processing. It is a lifecycle misuse error, not a data error.","triggerScenarios":"Constructing the model with enabled=False (or artifacts path invalid) so the engine is never created, then bypassing the enabled guard by calling the processing method directly; or a partial __init__ failure that left engine unset.","commonSituations":"Testing code that instantiates the model disabled but calls the batch method anyway; toggling options.enabled after construction without re-initializing; refactors that moved engine creation out of __init__.","solutions":["Ensure the model is constructed with enabled=True and a valid artifacts path so the engine loads during __init__.","Re-instantiate the model after changing enablement/options instead of mutating flags on an existing instance.","In tests, gate direct calls on model.enabled and engine presence: if not model.enabled, skip or pass elements through."],"exampleFix":"# before\nmodel = CodeFormulaVlmModel(enabled=False, ...)\nfor out in model(ctx, doc, batch):  # RuntimeError: Engine not initialized\n    ...\n\n# after\nmodel = CodeFormulaVlmModel(enabled=True, artifacts_path=path, ...)\nfor out in model(ctx, doc, batch):\n    ...","handlingStrategy":"validation","validationCode":"if model.enabled and model.engine is not None:\n    results = model(ctx, doc, batch)\nelse:\n    results = (el.item for el in batch)  # pass-through like the disabled path","typeGuard":null,"tryCatchPattern":"try:\n    for out in model(ctx, doc, batch):\n        process(out)\nexcept RuntimeError as err:\n    if \"Engine not initialized\" in str(err):\n        raise RuntimeError(\"Model was built disabled; construct with enabled=True\") from err\n    raise","preventionTips":["Construct the model with the final enabled/artifacts settings; never toggle flags afterwards.","Assert model.engine is not None right after constructing an enabled model, so failures surface at setup time.","In tests, skip direct batch calls on disabled models."],"tags":["code-formula","vlm","lifecycle","runtime"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}