roboflow/supervision · error · ValueError

resolution must be a tuple of two integers, got

Error message

            resolution must be a tuple of two integers, got
            {type(resolution)} with value {resolution}
            

What it means

Raised by supervision.validators._validate_resolution when a resolution argument is not a tuple of length 2. Resolution must be a (width, height) tuple of integers, used wherever supervision needs explicit frame/annotator dimensions.

Source

Thrown at src/supervision/validators/__init__.py:336

    xy: Any, class_id: Any, confidence: Any, data: dict[str, Any]
) -> None:
    void(xy, class_id, confidence, data)


@deprecated(  # type: ignore[untyped-decorator]
    target=_validate_keypoints_fields,
    deprecated_in="0.27.0",
    remove_in="0.31.0",
)
def validate_keypoints_fields(
    xy: Any, class_id: Any, confidence: Any, data: dict[str, Any]
) -> None:
    void(xy, class_id, confidence, data)


def _validate_resolution(resolution: Any) -> tuple[int, int]:
    if not (isinstance(resolution, tuple) and len(resolution) == 2):
        raise ValueError(
            f"""
            resolution must be a tuple of two integers, got
            {type(resolution)} with value {resolution}
            """
        )
    w, h = resolution
    if not (isinstance(w, int) and isinstance(h, int)):
        raise ValueError(
            f"""
            Both elements in resolution must be integers.
            Got types ({type(w)}, {type(h)})
            """
        )
    if w <= 0 or h <= 0:
        raise ValueError(
            f"Both dimensions in resolution must be positive. Got ({w}, {h})."
        )
    return w, h

View on GitHub (pinned to 7f254d9784)

Solutions

1. Pass an explicit 2-tuple: resolution=(1920, 1080).
2. Derive it from a frame: resolution=(frame.shape[1], frame.shape[0]).
3. Convert lists: resolution=tuple(resolution) after checking len == 2.
4. Note supervision uses (width, height) order, unlike NumPy's (h, w).

Example fix

# before
frame_info = video_frame.shape  # (1080, 1920, 3)
obj = SomeAPI(resolution=frame_info)  # 3-tuple -> ValueError

# after
h, w = video_frame.shape[:2]
obj = SomeAPI(resolution=(w, h))

if not (isinstance(resolution, tuple) and len(resolution) == 2):
    h, w = frame.shape[:2]
    resolution = (int(w), int(h))
obj = SomeAPI(resolution=resolution)

def is_valid_resolution_shape(resolution: Any) -> bool:
    return isinstance(resolution, tuple) and len(resolution) == 2

When it happens

Trigger: Passing resolution=(1920, 1080, 3) (a 3-tuple including channels), resolution=[1920, 1080] (a list), resolution=1920 (a bare int), or a numpy array.

Common situations: Forwarding frame.shape (which is (h, w, c)) as resolution; grabbing video resolution from an API that returns a list; passing width and height as separate positional values instead of one tuple.

Related errors

• Both dimensions in resolution must be positive. Got ({w}, {h
• Both elements in resolution must be integers.
• prefetch must be >= 0, got {prefetch}
• `slice_wh` must be an int or a tuple of two positive integer
• `overlap_wh` must be an int or a tuple of two non negative i

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