docling-project/docling · error · RuntimeError

Picture classifier engine is not initialized.

Error message

Picture classifier engine is not initialized.

What it means

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.

Source

Thrown at docling/models/stages/picture_classifier/document_picture_classifier.py:150

        ----------
        doc : DoclingDocument
            The document containing the elements to be processed.
        element_batch : Iterable[ItemAndImageEnrichmentElement]
            A batch of pictures to classify.

        Returns
        -------
        Iterable[NodeItem]
            An iterable of NodeItem objects after processing. The field
            'data.classification' is added containing the classification for each picture.
        """
        if not self.enabled:
            for element in element_batch:
                yield element.item
            return

        if self.engine is None:
            raise RuntimeError("Picture classifier engine is not initialized.")

        images: List[Union[Image.Image, np.ndarray]] = []
        elements: List[PictureItem] = []
        for i, el in enumerate(element_batch):
            assert isinstance(el.item, PictureItem)
            elements.append(el.item)

            raw_image = el.image
            if isinstance(raw_image, Image.Image):
                raw_image = raw_image.convert("RGB")
            elif isinstance(raw_image, np.ndarray):
                raw_image = Image.fromarray(raw_image).convert("RGB")
            else:
                raise TypeError(
                    "Supported input formats are PIL.Image.Image or numpy.ndarray."
                )
            images.append(raw_image)

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Let Docling construct the stage normally (enabled with a valid artifacts_path) so the engine is loaded during __init__.
2. If you intentionally run without classification, set enabled=False on the model so items pass through instead of raising.
3. Check that the classifier artifacts (model repo cache folder) were downloaded and the init path completed without swallowing exceptions.

Example fix

# before
classifier = DocumentPictureClassifierModel(enabled=True)  # engine never set

# after
classifier = DocumentPictureClassifierModel(enabled=False)
# or construct with valid artifacts_path so the engine loads

if classifier.enabled and classifier.engine is None:
    raise RuntimeError("picture classifier enabled but engine missing — reinitialize with artifacts")

def classifier_ready(model) -> bool:
    """True when the classifier can actually process batches."""
    return (not model.enabled) or model.engine is not None

try:
    yield from classifier(items)
except RuntimeError as e:
    if "engine is not initialized" in str(e):
        log.warning("picture classifier unavailable; passing images through unclassified")
        yield from (el.item for el in items)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Engine not initialized
• Supported input formats are PIL.Image.Image or numpy.ndarray
• No pipeline could be initialized for format {format}
• No pipeline could be initialized for {in_doc.file}.
• Extraction failed for: {ext_res.input.file} with status: {ex

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/baf3d99cef29f37d. Report an issue: GitHub.