{"record":{"id":"0db5b648c0586cf8","repo":"docling-project/docling","slug":"engine-not-initialized-0db5b6","errorCode":null,"errorMessage":"Engine not initialized","messagePattern":"Engine not initialized","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/models/stages/picture_description/picture_description_vlm_engine_model.py","lineNumber":163,"sourceCode":"                temperature=float(temperature),\n                max_new_tokens=int(max_new_tokens),\n                stop_strings=stop_strings,\n                extra_generation_config=extra_generation_config,\n            )\n            for image in image_list\n        ]\n\n    def _annotate_images(self, images: Iterable[Image.Image]) -> Iterable[str]:\n        \"\"\"Generate descriptions for a batch of images.\n\n        Args:\n            images: Iterable of PIL images to describe\n\n        Yields:\n            Description text for each image\n        \"\"\"\n        if self.engine is None:\n            raise RuntimeError(\"Engine not initialized\")\n\n        # Convert to list for batch processing\n        # TODO: Consider using chunking here\n        image_list = list(images)\n\n        if not image_list:\n            return\n\n        try:\n            # Prepare batch of engine inputs\n            engine_inputs = self._build_engine_inputs(image_list)\n\n            # Generate descriptions using batch prediction\n            outputs = self.engine.predict_batch(engine_inputs)\n\n            # Extract and yield descriptions\n            for output in outputs:\n                description = output.text.strip()","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/stages/picture_description/picture_description_vlm_engine_model.py#L145-L181","documentation":"The VLM picture-description model generates descriptions through self.engine (a local vision-language engine built on transformers). If the engine was never constructed (model built without a successful init), _annotate_images raises this RuntimeError as soon as a batch of images is submitted.","triggerScenarios":"Calling the model's annotation path (directly or via a pipeline run with picture description enabled) on an instance whose engine is None — typically constructed disabled or via a path that skipped engine loading.","commonSituations":"Programmatic construction without artifacts; test stubs; an exception during engine init being swallowed by custom glue code; calling internal methods on a half-initialized model.","solutions":["Construct the model through the normal factory path with enabled=True and a valid artifacts_path so the engine is created in __init__.","Guard calls: skip annotation when the model is disabled instead of invoking _annotate_images.","Log/inspect model.engine right after construction to confirm initialization succeeded."],"exampleFix":"# before\nmodel = PictureDescriptionVlmModel(enabled=False)\nmodel._annotate_images(images)  # RuntimeError\n\n# after\nmodel = PictureDescriptionVlmModel(enabled=True, artifacts_path=path)\ndescs = model._annotate_images(images) if model.engine else []","handlingStrategy":"type-guard","validationCode":"if vlm_model.engine is None:\n    raise RuntimeError(\"VLM engine not loaded — construct with enabled=True and valid artifacts_path\")","typeGuard":"def vlm_ready(model) -> bool:\n    return model.engine is not None","tryCatchPattern":"try:\n    descriptions = list(vlm_model._annotate_images(images))\nexcept RuntimeError as e:\n    if \"Engine not initialized\" in str(e):\n        log.warning(\"VLM unavailable; skipping picture descriptions\")\n        descriptions = [\"\"] * len(images)\n    else:\n        raise","preventionTips":["Check model.engine is not None before invoking annotation helpers.","Initialize models once at service startup and fail fast there.","Wrap model init so exceptions cannot be silently swallowed, leaving engine None."],"tags":["vlm","pictures","initialization","pipeline"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}