roboflow/supervision · error · ValueError

NumPy image must have at least 2 dimensions (H, W, ...). Rec

Error message

NumPy image must have at least 2 dimensions (H, W, ...). Received shape: {image.shape}

What it means

Raised by `sv.get_image_resolution_wh` when the input is an np.ndarray with fewer than 2 dimensions. Resolution is defined as `image.shape[:2]` (height, width), which is meaningless for a 0-D scalar or 1-D vector. The message includes the offending shape so the mismatch is obvious.

Source

Thrown at src/supervision/utils/image.py:639

    Raises:
        ValueError: If a `numpy.ndarray` image has fewer than 2 dimensions.
        TypeError: If `image` is not a supported type (`numpy.ndarray` or
            `PIL.Image.Image`).

    Examples:
        ```pycon
        >>> import numpy as np
        >>> import supervision as sv
        >>> image = np.zeros((1080, 1920, 3), dtype=np.uint8)
        >>> sv.get_image_resolution_wh(image)
        (1920, 1080)

        ```
    """
    if isinstance(image, np.ndarray):
        if image.ndim < 2:
            raise ValueError(
                "NumPy image must have at least 2 dimensions (H, W, ...). "
                f"Received shape: {image.shape}"
            )
        height, width = image.shape[:2]
        return int(width), int(height)

    if isinstance(image, Image.Image):
        width, height = image.size
        return int(width), int(height)

    raise TypeError(
        "`image` must be a numpy.ndarray or PIL.Image.Image. "
        f"Received type: {type(image)}"
    )


class ImageSink:
    """

View on GitHub (pinned to 7f254d9784)

Solutions

1. Pass the full 2-D frame: `image.shape` must be like (H, W) or (H, W, C).
2. If you hold flattened data with known geometry, reshape first: `flat.reshape(h, w, c)`.
3. Audit slicing: `image[0]` gives a row — use `image[0:1]` to keep 2-D.

Example fix

# before
res = sv.get_image_resolution_wh(frame[0])  # 1-D row
# after
res = sv.get_image_resolution_wh(frame)  # (H, W, 3)

if isinstance(image, np.ndarray):
    assert image.ndim >= 2, f'need 2-D image, got shape {image.shape}'

def is_2d_image(x: Any) -> bool:
    return isinstance(x, np.ndarray) and x.ndim >= 2

When it happens

Trigger: Passing a 1-D flattened pixel array, a single-row slice `image[0]` (shape (W, 3) or (W,)), or a numpy scalar from aggregating an image (e.g. `image.mean()`).

Common situations: Accidentally indexing one channel/row instead of the frame; functions that call `.ravel()` for transport and forget to reshape; passing a grayscale profile vector where a 2-D image was expected.

Related errors

• `image` must be a numpy.ndarray or PIL.Image.Image. Received
• masks_true and masks_detection must share the same (H, W); g
• Shape of np.ndarray for key '{key}' must be ({n},)
• First dimension of np.ndarray for key '{key}' must have size
• class_id must be 1d np.ndarray with (n, ) shape

AI-assisted analysis of roboflow/supervision@7f254d9784 (2026-08-15). Data as JSON: /api/errors/fd4406a4461f2c0d. Report an issue: GitHub.