What causes "Unrecognized image type {type(image)}" in huggingface/transformers?

Convert the input before use: `np.array(x)` for lists/tf tensors, or `torch.tensor(x)` for torch pipelines.

huggingface/transformers · error · ValueError

Unrecognized image type {type(image)}

Error message

Unrecognized image type {type(image)}

What it means

Raised by `transformers.image_utils.get_image_type()` when the input is not a PIL.Image.Image, not a torch.Tensor, and not a numpy.ndarray. This helper classifies images into an ImageType enum (PIL/TORCH/NUMPY); anything outside those three categories is unsupported. Downstream helpers like `is_valid_image` use the same three-way check, so unsupported types are rejected consistently across the image pipeline.

Source

Thrown at src/transformers/image_utils.py:115

def is_pil_image(img):
    return is_vision_available() and isinstance(img, PIL.Image.Image)


class ImageType(ExplicitEnum):
    PIL = "pillow"
    TORCH = "torch"
    NUMPY = "numpy"


def get_image_type(image):
    if is_pil_image(image):
        return ImageType.PIL
    if is_torch_tensor(image):
        return ImageType.TORCH
    if is_numpy_array(image):
        return ImageType.NUMPY
    raise ValueError(f"Unrecognized image type {type(image)}")


def is_valid_image(img):
    return is_pil_image(img) or is_numpy_array(img) or is_torch_tensor(img)


def is_valid_list_of_images(images: list):
    return images and all(is_valid_image(image) for image in images)


def concatenate_list(input_list):
    if isinstance(input_list[0], list):
        return [item for sublist in input_list for item in sublist]
    elif isinstance(input_list[0], np.ndarray):
        return np.concatenate(input_list, axis=0)
    elif isinstance(input_list[0], torch.Tensor):
        return torch.cat(input_list, dim=0)

View on GitHub (pinned to a597f97485)

Solutions

Convert the input before use: `np.array(x)` for lists/tf tensors, or `torch.tensor(x)` for torch pipelines.
For path/URL/base64 strings, use `transformers.image_utils.load_image(image)` instead of classification helpers.
Ensure the array is a real np.ndarray, not a pandas/bytes/other array-like.

Example fix

// before
type_ = get_image_type("cat.jpg")        # ValueError
type_ = get_image_type([[1,2],[3,4]])   # ValueError

// after
from transformers.image_utils import load_image
img = load_image("cat.jpg")              # str -> PIL image
type_ = get_image_type(img)              # ImageType.PIL

Defensive patterns

Strategy: type-guard

Type guard

from transformers.image_utils import is_valid_image

def as_supported_image(x):
    if not is_valid_image(x):
        raise TypeError(f"Expected PIL/numpy/torch image, got {type(x)}; load strings with load_image()")
    return x

Prevention

Load path/URL/base64 strings with load_image before any type classification.
Convert tf tensors and lists to np.ndarray at your pipeline entry point.
Never assume get_image_type will convert — it only classifies.

When it happens

Trigger: Calling `get_image_type()` with a TensorFlow/JAX tensor, a raw Python list or nested list, a file-path string, a bytes object, or a torch tensor that fails `is_torch_tensor` because torch is not importable in the environment.

Common situations: Users pass file paths or URLs expecting the function to load them (it doesn't — use `load_image`); TensorFlow pipelines feed tf.Tensor into a transformers image processor; or a minimal environment where torch is absent so torch tensors are not recognized.

Related errors

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/327ee6fc63305793. Report an issue: GitHub.