{"record":{"id":"baf3d99cef29f37d","repo":"docling-project/docling","slug":"picture-classifier-engine-is-not-initialized","errorCode":null,"errorMessage":"Picture classifier engine is not initialized.","messagePattern":"Picture classifier engine is not initialized\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/models/stages/picture_classifier/document_picture_classifier.py","lineNumber":150,"sourceCode":"        ----------\n        doc : DoclingDocument\n            The document containing the elements to be processed.\n        element_batch : Iterable[ItemAndImageEnrichmentElement]\n            A batch of pictures to classify.\n\n        Returns\n        -------\n        Iterable[NodeItem]\n            An iterable of NodeItem objects after processing. The field\n            'data.classification' is added containing the classification for each picture.\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(\"Picture classifier engine is not initialized.\")\n\n        images: List[Union[Image.Image, np.ndarray]] = []\n        elements: List[PictureItem] = []\n        for i, el in enumerate(element_batch):\n            assert isinstance(el.item, PictureItem)\n            elements.append(el.item)\n\n            raw_image = el.image\n            if isinstance(raw_image, Image.Image):\n                raw_image = raw_image.convert(\"RGB\")\n            elif isinstance(raw_image, np.ndarray):\n                raw_image = Image.fromarray(raw_image).convert(\"RGB\")\n            else:\n                raise TypeError(\n                    \"Supported input formats are PIL.Image.Image or numpy.ndarray.\"\n                )\n            images.append(raw_image)\n","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/stages/picture_classifier/document_picture_classifier.py#L132-L168","documentation":"The picture classifier stage requires a classification engine (e.g. a transformers image-classification pipeline loaded from artifacts). If the model was created disabled or failed/was never initialized, self.engine stays None, and processing a batch raises this RuntimeError. Disabled models short-circuit and pass items through, so this error means enabled=True but no engine.","triggerScenarios":"Constructing a picture classifier model with enabled=True but an init path that never assigned self.engine (e.g. artifacts loading skipped or an external construction), then feeding PictureItem batches through it.","commonSituations":"Custom pipeline assembly where a stage is instantiated enabled without downloading/loading weights; monkeypatched or test doubles that skip engine creation; artifacts_path pointing at an empty cache so engine construction silently did not happen.","solutions":["Let Docling construct the stage normally (enabled with a valid artifacts_path) so the engine is loaded during __init__.","If you intentionally run without classification, set enabled=False on the model so items pass through instead of raising.","Check that the classifier artifacts (model repo cache folder) were downloaded and the init path completed without swallowing exceptions."],"exampleFix":"# before\nclassifier = DocumentPictureClassifierModel(enabled=True)  # engine never set\n\n# after\nclassifier = DocumentPictureClassifierModel(enabled=False)\n# or construct with valid artifacts_path so the engine loads","handlingStrategy":"type-guard","validationCode":"if classifier.enabled and classifier.engine is None:\n    raise RuntimeError(\"picture classifier enabled but engine missing — reinitialize with artifacts\")","typeGuard":"def classifier_ready(model) -> bool:\n    \"\"\"True when the classifier can actually process batches.\"\"\"\n    return (not model.enabled) or model.engine is not None","tryCatchPattern":"try:\n    yield from classifier(items)\nexcept RuntimeError as e:\n    if \"engine is not initialized\" in str(e):\n        log.warning(\"picture classifier unavailable; passing images through unclassified\")\n        yield from (el.item for el in items)\n    else:\n        raise","preventionTips":["Assert engine is not None right after model construction in integration tests.","Treat disabled stages as pass-through instead of calling their processing path.","Construct stages through the documented factories so init invariants hold."],"tags":["classification","pipeline","initialization","pictures"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}