docling-project/docling · error · TypeError

Supported input formats are PIL.Image.Image or numpy.ndarray

Error message

Supported input formats are PIL.Image.Image or numpy.ndarray.

What it means

Inside the picture-classifier batch loop, each element's image must be either a PIL Image or a numpy ndarray; anything else (None, a path string, bytes, a torch tensor) raises this TypeError after PIL/ndarray conversion is attempted.

Source

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

                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)

        engine_input_batch = [
            ImageClassificationEngineInput(image=image) for image in images
        ]
        engine_output_batch = self.engine.predict_batch(engine_input_batch)

        for item, output in zip(elements, engine_output_batch):
            predicted_classes = [
                PictureClassificationClass(
                    class_name=self._classes[label_id],
                    confidence=score,
                )
                for label_id, score in zip(output.label_ids, output.scores)
            ]

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Ensure each element's image attribute is a PIL.Image.Image or numpy.ndarray before feeding the stage (load paths with PIL.open / np.asarray).
2. Check upstream stages that populate el.image; verify none yield None for failed extractions.
3. If writing custom pipeline glue, convert explicitly: Image.open(path).convert('RGB').

Example fix

# before
item.image = "figures/fig1.png"  # path string

# after
from PIL import Image
item.image = Image.open("figures/fig1.png").convert("RGB")

from PIL import Image
import numpy as np

def valid_batch(batch) -> bool:
    return all(
        isinstance(el.image, (Image.Image, np.ndarray)) for el in batch
    )

from PIL import Image
import numpy as np
from typing import Union

def is_classifiable_image(img: object) -> bool:
    return isinstance(img, (Image.Image, np.ndarray))

try:
    classifier(items)
except TypeError as e:
    if "Supported input formats" in str(e):
        items = [normalize(el) for el in items]  # load paths/None -> PIL.Image
    else:
        raise

When it happens

Trigger: Feeding a batch where el.image is not PIL.Image.Image/np.ndarray — e.g. an element built manually with a file path or bytes as image, or a custom pipeline stage that yields wrapper items with the wrong image attribute type.

Common situations: Custom NodeItem/PictureItem construction in tests or bespoke pipelines; upgrading pipelines that previously passed paths; elements whose image extraction failed upstream leaving None.

Related errors

• Picture classifier engine is not initialized.
• prompt must be str or list[str], got {type(prompt)}
• Cannot convert Box Note with hash {self.document_hash}: no '
• Cannot convert doc with {self.document_hash} because the bac
• Unsupported input type: {type(self.path_or_stream)}

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