roboflow/supervision · error · ValueError

`overlap_wh` must be a non negative integer. Received: {over

Error message

`overlap_wh` must be a non negative integer. Received: {overlap_wh}

What it means

Raised by InferenceSlicer._normalize_overlap_wh when the overlap_wh parameter passed as a plain int is negative. overlap_wh controls how many pixels adjacent inference slices overlap so objects on slice borders are still detected; a negative overlap has no meaning and would corrupt slice-offset generation.

Source

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

            if width <= 0 or height <= 0:
                raise ValueError(
                    f"`slice_wh` values must be positive. Received: {slice_wh}"
                )
            return width, height

        raise ValueError(
            "`slice_wh` must be an int or a tuple of two positive integers "
            "(slice_w, slice_h). "
            f"Received: {slice_wh}"
        )

    @staticmethod
    def _normalize_overlap_wh(
        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}"
        )

View on GitHub (pinned to 7f254d9784)

Solutions

1. Pass a non-negative integer, e.g. overlap_wh=16.
2. If computing overlap dynamically, clamp it: max(0, computed_overlap).
3. If you need per-axis overlap, pass a tuple of two non-negative ints instead, e.g. overlap_wh=(16, 32).
4. Check that overlap_wh is smaller than the corresponding slice_wh dimension so slices still advance.

Example fix

# before
slicer = InferenceSlicer(slice_wh=(512, 512), overlap_wh=-16)

# after
slicer = InferenceSlicer(slice_wh=(512, 512), overlap_wh=16)

overlap = int(user_overlap)
if overlap < 0:
    raise ValueError(f"overlap_wh must be >= 0, got {overlap}")
slicer = InferenceSlicer(slice_wh=(512, 512), overlap_wh=max(0, overlap))

def is_valid_overlap(overlap: int | tuple[int, int]) -> bool:
    if isinstance(overlap, int):
        return overlap >= 0
    return (
        isinstance(overlap, tuple)
        and len(overlap) == 2
        and all(isinstance(v, int) and v >= 0 for v in overlap)
    )

When it happens

Trigger: Calling InferenceSlicer(slice_wh=(512, 512), overlap_wh=-16) or passing any negative int as overlap_wh to the InferenceSlicer constructor.

Common situations: Copy-pasting a negative padding/margin value from other config into overlap_wh; sign errors when computing overlap programmatically (e.g. overlap = min_dim - margin going below zero); confusing overlap (must be >= 0) with stride/step offsets.

Related errors

• `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
• `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}

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