roboflow/supervision · error · ValueError

`overlap_wh` must be an int or a tuple of two non negative i

Error message

`overlap_wh` must be an int or a tuple of two non negative integers (overlap_w, overlap_h). Received: {overlap_wh}

What it means

Raised by InferenceSlicer's _normalize_overlap_wh when overlap_wh is neither an int nor a 2-tuple of ints. Overlap defines how many pixels adjacent slices share; floats, strings, lists, or tuples of the wrong length cannot describe that and are rejected during construction.

Source

Thrown at src/supervision/detection/tools/inference_slicer.py:687

        overlap_wh: int | tuple[int, int],
    ) -> tuple[int, int]:
        if isinstance(overlap_wh, int):
            if overlap_wh < 0:
                raise ValueError(
                    "`overlap_wh` must be a non negative integer. "
                    f"Received: {overlap_wh}"
                )
            return overlap_wh, overlap_wh

        if isinstance(overlap_wh, tuple) and len(overlap_wh) == 2:
            overlap_w, overlap_h = overlap_wh
            if overlap_w < 0 or overlap_h < 0:
                raise ValueError(
                    f"`overlap_wh` values must be non negative. Received: {overlap_wh}"
                )
            return overlap_w, overlap_h

        raise ValueError(
            "`overlap_wh` must be an int or a tuple of two non negative integers "
            "(overlap_w, overlap_h). "
            f"Received: {overlap_wh}"
        )

    @staticmethod
    def _generate_offset(
        resolution_wh: tuple[int, int],
        slice_wh: tuple[int, int],
        overlap_wh: tuple[int, int],
    ) -> npt.NDArray[Any]:
        """
        Generate bounding boxes defining the coordinates of image slices with overlap.

        Args:
            resolution_wh: Image resolution `(width, height)`.
            slice_wh: Size of each slice `(width, height)`.
            overlap_wh: Overlap size between slices `(width, height)`.

View on GitHub (pinned to 7f254d9784)

Solutions

1. Pass an int pixel count (overlap_wh=128) or an int 2-tuple (overlap_wh=(128, 64)); 0 is allowed.
2. If you think in ratios, convert first: overlap_wh = int(0.25 * slice_w).
3. Coerce config-sourced values to int/tuple at load time.

Example fix

# before
slicer = sv.InferenceSlicer(callback=cb, slice_wh=512, overlap_wh=0.25)  # ValueError

# after
slicer = sv.InferenceSlicer(callback=cb, slice_wh=512, overlap_wh=int(0.25 * 512))

def normalize_overlap_wh(v):
    if isinstance(v, (list, tuple)):
        v = tuple(int(x) for x in v)
    else:
        v = int(v)
    return v

slicer = sv.InferenceSlicer(callback=cb, overlap_wh=normalize_overlap_wh(cfg['overlap_wh']))

def is_valid_overlap_wh(v) -> bool:
    if isinstance(v, int):
        return v >= 0
    return isinstance(v, tuple) and len(v) == 2 and all(isinstance(x, int) and x >= 0 for x in v)

When it happens

Trigger: Constructing sv.InferenceSlicer(callback=..., overlap_wh=0.2) (a ratio instead of pixels), overlap_wh=[128], or overlap_wh="128".

Common situations: Confusing overlap_wh with a fraction (0.2) the way IoU thresholds work; config files that parse numbers as floats or sequences as lists.

Related errors

• `slice_wh` must be an int or a tuple of two positive integer
• `thread_workers` must be a positive integer. Received: {thre
• `batch_size` must be a positive integer. Received: {batch_si
• `slice_wh` must be a positive integer. Received: {slice_wh}
• `slice_wh` values must be positive. Received: {slice_wh}

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