What causes "Unsupported image type for PP-DocLayoutV2: {type(image)}" in opendatalab/MinerU?

Load the file first: PIL.Image.open(path) or cv2.imread(path) (ndarray is accepted).

opendatalab/MinerU · error · TypeError

Unsupported image type for PP-DocLayoutV2

Error message

Unsupported image type for PP-DocLayoutV2: {type(image)}

What it means

TypeError raised by PPDocLayoutV2LayoutModel._preprocess_single_image when the image argument is neither a numpy ndarray nor a PIL Image. Preprocessing immediately converts to PIL for RGB conversion and tensor transforms, so any other type (str path, bytes, torch tensor, cv2 GPU mat) fails this isinstance check.

Solutions

Load the file first: PIL.Image.open(path) or cv2.imread(path) (ndarray is accepted).
Convert tensors: img = torchvision.transforms.functional.to_pil_image(tensor).
For bytes: io.BytesIO(data) wrapped in Image.open(...).
Check type before calling predict and normalize to ndarray/PIL.

Example fix

# before
model.predict(image='/data/page1.png')  # TypeError

# after
from PIL import Image
model.predict(image=Image.open('/data/page1.png').convert('RGB'))

Defensive patterns

Strategy: type-guard

Validate before calling

from PIL import Image
import numpy as np

def as_model_image(image):
    if isinstance(image, Image.Image):
        return image
    if isinstance(image, np.ndarray):
        return image
    if isinstance(image, (str, bytes)):
        return Image.open(image if isinstance(image, str) else __import__('io').BytesIO(image))
    raise TypeError(f'unsupported image type {type(image)!r}')

Type guard

def is_supported_image(image) -> bool:
    import numpy as np
    from PIL import Image
    return isinstance(image, (np.ndarray, Image.Image))

Try / catch

try:
    model.predict(image=img)
except TypeError as e:
    if 'Unsupported image type' in str(e):
        img = Image.open(img).convert('RGB')  # it was a path/bytes
        model.predict(image=img)
    else:
        raise

Prevention

Open files with PIL (or cv2) before calling predict — paths are not accepted.
Centralize image loading in one adapter that returns ndarray/PIL.
Convert decoded bytes via io.BytesIO + Image.open at the boundary.

When it happens

Trigger: predict(image='/data/page1.png'), predict(image=torch.Tensor(...)), or passing raw bytes from an HTTP response; also URLs or pathlib.Path objects.

Common situations: Users assuming the API accepts file paths (common with YOLO-style predict APIs); pipelines that read files with cv2 but pass a path variable by mistake; passing a tensor produced by an earlier preprocessing stage.

Related errors

AI-assisted analysis of opendatalab/MinerU@4fe4bde114 (2026-08-14). Data as JSON: /api/errors/9349b3b36fa04e5d. Report an issue: GitHub.

Appendix: source

Thrown at mineru/model/layout/pp_doclayoutv2.py:955

        batch_size, sequence_length, _ = order_scores.shape
        order_votes = order_scores.triu(diagonal=1).sum(dim=1) + (
            1.0 - order_scores.transpose(1, 2)
        ).tril(diagonal=-1).sum(dim=1)
        order_pointers = torch.argsort(order_votes, dim=1)
        order_seq = torch.empty_like(order_pointers)
        ranks = torch.arange(sequence_length, device=order_pointers.device, dtype=order_pointers.dtype).expand(
            batch_size, -1
        )
        order_seq.scatter_(1, order_pointers, ranks)
        return order_seq

    def _preprocess_single_image(self, image: Union[np.ndarray, Image.Image]) -> Tuple[torch.Tensor, Tuple[int, int]]:
        if isinstance(image, np.ndarray):
            pil_image = Image.fromarray(image)
        elif isinstance(image, Image.Image):
            pil_image = image
        else:
            raise TypeError(f"Unsupported image type for PP-DocLayoutV2: {type(image)}")

        pil_image = pil_image.convert("RGB")
        target_size = pil_image.size[1], pil_image.size[0]
        pixel_values = tvF.pil_to_tensor(pil_image)
        pixel_values = tvF.resize(
            pixel_values,
            size=[self.imgsz[1], self.imgsz[0]],
            interpolation=InterpolationMode.BICUBIC,
            antialias=False,
        )
        pixel_values = pixel_values.to(dtype=torch.float32) * self.rescale_factor
        return pixel_values, target_size

    def _post_process_object_detection(
        self,
        outputs: PPDocLayoutV2ForObjectDetectionOutput,
        target_sizes: Sequence[Tuple[int, int]],
    ) -> List[Dict[str, torch.Tensor]]:

View on GitHub (pinned to 4fe4bde114)