{"record":{"id":"d851627ac893f83c","repo":"huggingface/transformers","slug":"could-not-make-a-flat-list-of-images-from-images","errorCode":null,"errorMessage":"Could not make a flat list of images from {images}","messagePattern":"Could not make a flat list of images from (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/image_utils.py","lineNumber":237,"sourceCode":"        isinstance(images, (list, tuple))\n        and all(isinstance(images_i, (list, tuple)) for images_i in images)\n        and all(is_valid_list_of_images(images_i) or not images_i for images_i in images)\n    ):\n        return [img for img_list in images for img in img_list]\n\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 [img for img_list in images for img in img_list]\n\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(f\"Could not make a flat list of images from {images}\")\n\n\ndef make_nested_list_of_images(\n    images: list[ImageInput] | ImageInput,\n    expected_ndims: int = 3,\n) -> list[ImageInput]:\n    \"\"\"\n    Ensure that the output is a nested 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 list of images or a list of 4d array of images.\n    \"\"\"\n    # If it's a list of batches, it's already in the right format\n    if (","sourceCodeStart":219,"sourceCodeEnd":255,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/image_utils.py#L219-L255","documentation":"Raised by `transformers.image_utils.make_flat_list_of_images` (default `expected_ndims=3`) when the input's structure cannot be flattened into a list of single images. The helper accepts: a list of valid images each with ndim == expected_ndims, a list of batches each with ndim == expected_ndims + 1, a single image, or a single batch tensor. Any other combination — wrong rank per element, lists of lists of lists, or a non-image type — reaches this catch-all ValueError.","triggerScenarios":"Passing a doubly-nested list [[[img, img], [img, img]]] (more than two levels); a list whose elements are 2D arrays when expected_ndims=3; a mixed list like [PIL_image, np_2d_array]; or an input like a plain string. Typically reached through `processor.preprocess()` on processors that flatten inputs.","commonSituations":"Batched inference code wrapping already-nested batches one more time; grayscale/mask arrays that dropped a channel axis; heterogeneous data lists where one element has a different shape than the rest.","solutions":["Flatten your input to at most one level of nesting over single images: `[img for batch in batches for img in batch]`.","Ensure every element is a valid image (PIL/np/torch) with exactly `expected_ndims` dimensions — add the channel axis back to 2D arrays.","Load any path/URL strings with `load_images()` before passing them in.","Set `expected_ndims` to match your data if you genuinely have a different rank (e.g. 2 for masks)."],"exampleFix":"// before\nflat = make_flat_list_of_images([[[img1, img2], [img3]]])  # too deeply nested\nflat = make_flat_list_of_images([np.zeros((h, w))])        # 2D element -> ValueError\n\n// after\nflat = make_flat_list_of_images([img1, img2, img3])\nflat = make_flat_list_of_images([np.zeros((1, h, w))])","handlingStrategy":"validation","validationCode":"from transformers.image_utils import is_valid_image\n\ndef flatten_images(maybe_nested, expected_ndims: int = 3):\n    flat = [img for sub in maybe_nested for img in sub] if maybe_nested and isinstance(maybe_nested[0], (list, tuple)) else maybe_nested\n    flat = flat if isinstance(flat, (list, tuple)) else [flat]\n    assert all(is_valid_image(i) and (not hasattr(i, \"ndim\") or i.ndim == expected_ndims) for i in flat)\n    return list(flat)","typeGuard":"from transformers.image_utils import is_valid_image\n\ndef is_flattenable(x, expected_ndims: int = 3) -> bool:\n    if is_valid_image(x):\n        return not hasattr(x, \"ndim\") or x.ndim in (expected_ndims, expected_ndims + 1)\n    return isinstance(x, (list, tuple)) and bool(x) and all(\n        is_valid_image(i) and (not hasattr(i, \"ndim\") or i.ndim == expected_ndims) for i in x\n    )","tryCatchPattern":null,"preventionTips":["Normalize inputs to one flat list of 3D images before calling processors.","Log element shapes/depths of image containers while developing batched pipelines.","Guarantee every element has exactly expected_ndims dimensions."],"tags":["image-processing","shape-validation","nesting","batching"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}