{"record":{"id":"6872017196fb51cb","repo":"huggingface/transformers","slug":"invalid-image-type-expected-either-pil-image-imag","errorCode":null,"errorMessage":"Invalid image type. Expected either PIL.Image.Image, numpy.ndarray, or torch.Tensor, but got {type(images)}.","messagePattern":"Invalid image type\\. Expected either PIL\\.Image\\.Image, numpy\\.ndarray, or torch\\.Tensor, but got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/image_utils.py","lineNumber":197,"sourceCode":"    # Either the input is a single image, in which case we create a list of length 1\n    if is_pil_image(images):\n        # PIL images are never batched\n        return [images]\n\n    if is_valid_image(images):\n        if images.ndim == expected_ndims + 1:\n            # Batch of images\n            images = list(images)\n        elif images.ndim == expected_ndims:\n            # Single image\n            images = [images]\n        else:\n            raise ValueError(\n                f\"Invalid image shape. Expected either {expected_ndims + 1} or {expected_ndims} dimensions, but got\"\n                f\" {images.ndim} dimensions.\"\n            )\n        return images\n    raise ValueError(\n        f\"Invalid image type. Expected either PIL.Image.Image, numpy.ndarray, or torch.Tensor, but got {type(images)}.\"\n    )\n\n\ndef make_flat_list_of_images(\n    images: list[ImageInput] | ImageInput,\n    expected_ndims: int = 3,\n) -> ImageInput:\n    \"\"\"\n    Ensure that the output is a flat list of images. If the input is a single image, it is converted to a list of length 1.\n    If the input is a nested list of images, it is converted to a flat list of images.\n    Args:\n        images (`Union[list[ImageInput], ImageInput]`):\n            The input image.\n        expected_ndims (`int`, *optional*, defaults to 3):\n            The expected number of dimensions for a single input image.\n    Returns:\n        list: A list of images or a 4d array of images.","sourceCodeStart":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/image_utils.py#L179-L215","documentation":"Raised by `transformers.image_utils.make_list_of_images` as its final fallthrough when the input is neither a PIL.Image.Image, a numpy.ndarray, nor a torch.Tensor (the `is_valid_image` check failed). The message names the three accepted types and the actual type received. It is an input-contract error: the helper only re-packages valid images into a list and never converts or loads anything.","triggerScenarios":"Calling `make_list_of_images()` (or an image processor preprocess path that uses it) with a TensorFlow tensor, a plain Python list of numbers (not a list of images), a string path, bytes, or None.","commonSituations":"Passing a raw file path or URL string to `preprocess` instead of loading it first with `load_image`/`load_images`; mixing TensorFlow/Keras pipelines with transformers image processors; passing None from a failed upstream load.","solutions":["Load strings first: `image = load_image('path_or_url_or_base64')` produces a PIL image the helper accepts.","Convert non-supported tensors: `np.array(x)` or `x.numpy()` for tf tensors.","For batches, pass a list/tuple whose elements are each PIL/np/torch images, e.g. `[img1, img2]`."],"exampleFix":"// before\ninputs = processor(images=\"/data/cat.jpg\", return_tensors=\"pt\")  # ValueError\n\n// after\nfrom transformers.image_utils import load_image\ninputs = processor(images=load_image(\"/data/cat.jpg\"), return_tensors=\"pt\")","handlingStrategy":"type-guard","validationCode":"from transformers.image_utils import is_valid_image, is_valid_list_of_images\n\nassert is_valid_image(images) or is_valid_list_of_images(images), (\n    f\"Expected PIL.Image, np.ndarray, or torch.Tensor (or list of them), got {type(images)}\"\n)","typeGuard":"from transformers.image_utils import is_valid_image\n\ndef is_acceptable_image_input(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":["Convert all inputs to PIL/np/torch at ingestion; load strings with load_image.","Use the library's own is_valid_image guard in data-loading wrappers.","Harden upstream loads so None never reaches preprocess."],"tags":["image-processing","type-checking","argument-validation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}