{"record":{"id":"ed1532c60cbaf23d","repo":"huggingface/transformers","slug":"invalid-image-type-type-img","errorCode":null,"errorMessage":"Invalid image type: {type(img)}","messagePattern":"Invalid image type: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/image_utils.py","lineNumber":281,"sourceCode":"    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:\n        image (`np.ndarray`):\n            The image to infer the channel dimension of.\n        num_channels (`int` or `tuple[int, ...]`, *optional*, defaults to `(1, 3)`):\n            The number of channels of the image.\n","sourceCodeStart":263,"sourceCodeEnd":299,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/image_utils.py#L263-L299","documentation":"Raised by `transformers.image_utils.to_numpy_array` when its argument fails `is_valid_image` — i.e. it is not a PIL.Image.Image, numpy.ndarray, or torch.Tensor. This function is the standard bridge used inside image processors to convert any supported image input to np.ndarray, and it deliberately refuses anything it would have to guess how to convert. The error names the offending type to make the mismatch obvious.","triggerScenarios":"Calling `to_numpy_array()` (or a processor path that uses it) with a TensorFlow tensor, a plain list, a string path/URL, bytes, or None. Note the string branch of the message is misleading: paths must be loaded with `load_image` first.","commonSituations":"Feeding tf.Tensor from a TF/Keras pipeline into a transformers image processor; passing raw nested lists built from pixel data instead of an ndarray; a None slipping through from a failed upstream load.","solutions":["Convert first: `np.asarray(x)` for lists/tf tensors, `x.numpy()` for tf eager tensors.","For paths/URLs/base64 strings, use `load_image(image)` which returns a PIL image.","Guard upstream code against None before calling conversion helpers."],"exampleFix":"// before\narr = to_numpy_array(\"/data/cat.jpg\")   # ValueError\narr = to_numpy_array(tf_tensor)         # ValueError\n\n// after\nfrom transformers.image_utils import load_image\narr = to_numpy_array(load_image(\"/data/cat.jpg\"))\narr = to_numpy_array(tf_tensor.numpy())","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"from transformers.image_utils import is_valid_image\n\ndef is_convertible_image(x) -> bool:\n    return is_valid_image(x)","tryCatchPattern":null,"preventionTips":["Convert tf.Tensor -> .numpy() and lists -> np.asarray at pipeline entry.","Load strings via load_image; to_numpy_array never loads.","Reject None early after any upstream fetch/open."],"tags":["image-processing","type-checking","numpy","argument-validation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}