{"record":{"id":"1ffd7c700f58c5c8","repo":"roboflow/supervision","slug":"the-number-of-images-exceeds-the-grid-size-please","errorCode":null,"errorMessage":"The number of images exceeds the grid size. Please increase the grid size or reduce the number of images.","messagePattern":"The number of images exceeds the grid size\\. Please increase the grid size or reduce the number of images\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/utils/notebook.py","lineNumber":101,"sourceCode":"        >>> from PIL import Image\n        >>> image1 = np.zeros((100, 100, 3), dtype=np.uint8)\n        >>> image2 = Image.new('RGB', (100, 100))\n        >>> image3 = np.zeros((100, 100, 3), dtype=np.uint8)\n        >>> images = [image1, image2, image3]\n        >>> titles = [\"Image 1\", \"Image 2\", \"Image 3\"]\n        >>> sv.plot_images_grid(images, grid_size=(2, 2), titles=titles, size=(16, 16))\n        ...\n\n        ```\n    \"\"\"\n    nrows, ncols = grid_size\n\n    images_np: list[npt.NDArray[np.uint8]] = [\n        pillow_to_cv2(img) if isinstance(img, Image.Image) else img for img in images\n    ]\n\n    if len(images_np) > nrows * ncols:\n        raise ValueError(\n            \"The number of images exceeds the grid size. Please increase the grid size\"\n            \" or reduce the number of images.\"\n        )\n\n    # Keep pyplot lazy so importing notebook helpers does not import matplotlib.\n    import matplotlib.pyplot as plt\n\n    _fig, axes = plt.subplots(nrows=nrows, ncols=ncols, figsize=size)\n\n    for idx, ax in enumerate(axes.flat):\n        if idx < len(images_np):\n            if images_np[idx].ndim == 2:\n                ax.imshow(images_np[idx], cmap=cmap)\n            else:\n                ax.imshow(cv2.cvtColor(images_np[idx], cv2.COLOR_BGR2RGB))\n\n            if titles is not None and idx < len(titles):\n                ax.set_title(titles[idx])","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/utils/notebook.py#L83-L119","documentation":"Raised by plot_images_grid() in supervision.utils.notebook when len(images) exceeds nrows*ncols of the requested grid_size. The helper lays images onto a fixed matplotlib grid, so extra images have nowhere to go and it fails fast instead of silently dropping them.","triggerScenarios":"Calling sv.plot_images_grid(images, grid_size=(2, 2)) with 5+ images; computing grid_size from a stale count after appending images; passing a (rows, cols) tuple where rows and cols are swapped relative to intent.","commonSituations":"Visualizing a dynamic batch of frames or dataset samples with a hardcoded grid; dataset size changes between runs while grid_size stays fixed; off-by-one when deriving cols = n // rows and n is not divisible.","solutions":["Derive the grid from the image count: grid_size=(ceil(n / cols), cols).","Trim the images to fit: images[:nrows*ncols].","If you swapped the tuple, remember grid_size is (nrows, ncols), not (width, height)."],"exampleFix":"// before\nsv.plot_images_grid(images, grid_size=(2, 2))  # 7 images -> ValueError\n\n// after\ncols = 4\nrows = math.ceil(len(images) / cols)\nsv.plot_images_grid(images, grid_size=(rows, cols))","handlingStrategy":"validation","validationCode":"n = len(images)\nrows = math.ceil(n / ncols)\nassert rows * ncols >= n\nsv.plot_images_grid(images, grid_size=(rows, ncols))","typeGuard":null,"tryCatchPattern":"try:\n    sv.plot_images_grid(images, grid_size=grid)\nexcept ValueError as e:\n    if 'exceeds the grid size' in str(e):\n        images = images[: grid[0] * grid[1]]\n        sv.plot_images_grid(images, grid_size=grid)\n    else:\n        raise","preventionTips":["Always compute grid_size from len(images), never hardcode it for dynamic batches.","Cap preview sample counts before plotting (e.g. images[:16])."],"tags":["visualization","matplotlib","notebook","validation"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}