{"record":{"id":"d80b640c68a6dcc3","repo":"huggingface/transformers","slug":"invalid-input-type-must-be-a-single-image-a-list","errorCode":null,"errorMessage":"Invalid input type. Must be a single image, a list of images, or a list of batches of images.","messagePattern":"Invalid input type\\. Must be a single image, a list of images, or a list of batches of images\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/image_utils.py","lineNumber":276,"sourceCode":"        and all(is_valid_list_of_images(images_i) or not images_i for images_i in images)\n    ):\n        return images\n\n    # If it's a list of images, it's a single batch, so convert it to a list of lists\n    if isinstance(images, (list, tuple)) and is_valid_list_of_images(images):\n        if is_pil_image(images[0]) or images[0].ndim == expected_ndims:\n            return [images]\n        if images[0].ndim == expected_ndims + 1:\n            return [list(image) for image in images]\n\n    # If it's a single image, convert it to a list of lists\n    if is_valid_image(images):\n        if is_pil_image(images) or images.ndim == expected_ndims:\n            return [[images]]\n        if images.ndim == expected_ndims + 1:\n            return [list(images)]\n\n    raise ValueError(\"Invalid input type. Must be a single image, a list of images, or a list of batches of images.\")\n\n\ndef to_numpy_array(img) -> np.ndarray:\n    if not is_valid_image(img):\n        raise ValueError(f\"Invalid image type: {type(img)}\")\n\n    if is_vision_available() and isinstance(img, PIL.Image.Image):\n        return np.array(img)\n    return to_numpy(img)\n\n\ndef infer_channel_dimension_format(\n    image: np.ndarray, num_channels: int | tuple[int, ...] | None = None\n) -> ChannelDimension:\n    \"\"\"\n    Infers the channel dimension format of `image`.\n\n    Args:","sourceCodeStart":258,"sourceCodeEnd":294,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/image_utils.py#L258-L294","documentation":"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.","triggerScenarios":"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.","commonSituations":"Video/multi-crop pipelines producing extra nesting levels; mask or grayscale inputs that lost a dimension; passing file paths instead of loaded images.","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."],"exampleFix":"// before\nnested = make_nested_list_of_images([[[img1, img2]]])  # ValueError\n\n// after\nnested = make_nested_list_of_images([[img1, img2]])    # list of single images -> [[img1, img2]]","handlingStrategy":"validation","validationCode":"from transformers.image_utils import is_valid_image\n\ndef nest_images(x, expected_ndims: int = 3):\n    assert is_valid_image(x) or (isinstance(x, (list, tuple)) and x and all(is_valid_image(i) for i in x)), (\n        \"input must be an image or a list of images\"\n    )\n    return x","typeGuard":"from transformers.image_utils import is_valid_image\n\ndef is_nestable(x) -> bool:\n    return is_valid_image(x) or (isinstance(x, (list, tuple)) and bool(x) and all(is_valid_image(i) for i in x))","tryCatchPattern":null,"preventionTips":["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)."],"tags":["image-processing","shape-validation","nesting","batching"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}