huggingface/transformers · error · ValueError

Invalid input type. Must be a single image, a list of images

Error message

Invalid input type. Must be a single image, a list of images, or a list of batches of images.

What it means

Raised by `transformers.image_utils.make_nested_list_of_images` (default `expected_ndims=3`) as the final fallthrough when the input cannot be represented as a list of batches of images. The helper accepts a list of single images (ndim == expected_ndims), a list of batch tensors (ndim == expected_ndims + 1), a single image, or a single batch tensor; anything else — wrong element ranks, triple nesting, or non-image types — fails every branch and raises this ValueError.

Source

Thrown at src/transformers/image_utils.py:276

        and all(is_valid_list_of_images(images_i) or not images_i for images_i in images)
    ):
        return images

    # If it's a list of images, it's a single batch, so convert it to a list of lists
    if isinstance(images, (list, tuple)) and is_valid_list_of_images(images):
        if is_pil_image(images[0]) or images[0].ndim == expected_ndims:
            return [images]
        if images[0].ndim == expected_ndims + 1:
            return [list(image) for image in images]

    # If it's a single image, convert it to a list of lists
    if is_valid_image(images):
        if is_pil_image(images) or images.ndim == expected_ndims:
            return [[images]]
        if images.ndim == expected_ndims + 1:
            return [list(images)]

    raise ValueError("Invalid input type. Must be a single image, a list of images, or a list of batches of images.")


def to_numpy_array(img) -> np.ndarray:
    if not is_valid_image(img):
        raise ValueError(f"Invalid image type: {type(img)}")

    if is_vision_available() and isinstance(img, PIL.Image.Image):
        return np.array(img)
    return to_numpy(img)


def infer_channel_dimension_format(
    image: np.ndarray, num_channels: int | tuple[int, ...] | None = None
) -> ChannelDimension:
    """
    Infers the channel dimension format of `image`.

    Args:

View on GitHub (pinned to a597f97485)

Solutions

Reduce nesting to: single image, batch tensor, list of images, or list of batch tensors — nothing deeper.
Fix element ranks: each single image must have ndim == expected_ndims (3 for standard images).
Load strings with `load_images()` first.
Set `expected_ndims` explicitly if your data is not standard 3D imagery.

Example fix

// before
nested = make_nested_list_of_images([[[img1, img2]]])  # ValueError

// after
nested = make_nested_list_of_images([[img1, img2]])    # list of single images -> [[img1, img2]]

Defensive patterns

Strategy: validation

Validate before calling

from transformers.image_utils import is_valid_image

def nest_images(x, expected_ndims: int = 3):
    assert is_valid_image(x) or (isinstance(x, (list, tuple)) and x and all(is_valid_image(i) for i in x)), (
        "input must be an image or a list of images"
    )
    return x

Type guard

from transformers.image_utils import is_valid_image

def is_nestable(x) -> bool:
    return is_valid_image(x) or (isinstance(x, (list, tuple)) and bool(x) and all(is_valid_image(i) for i in x))

Prevention

Cap nesting at two levels (list of images or list of batches) before preprocess.
Validate container structure with is_valid_list_of_images at data loading.
Match element rank to expected_ndims (3 for standard images).

When it happens

Trigger: Passing a triple-nested list [[[img, img]]]; a list whose elements are 2D arrays when 3D are expected; a single 5D tensor; a string or a tf.Tensor. Reached via image processor preprocess paths that require grouped (batched) inputs.

Common situations: Video/multi-crop pipelines producing extra nesting levels; mask or grayscale inputs that lost a dimension; passing file paths instead of loaded images.

Related errors

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