roboflow/supervision · error · ValueError

`batch_size` must be a positive integer. Received: {batch_si

Error message

`batch_size` must be a positive integer. Received: {batch_size}

What it means

Raised by InferenceSlicer.__init__ when batch_size is less than 1. batch_size controls how many image slices are handed to the callback per call; zero or negative batches cannot be formed, so construction fails.

Source

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

        overlap_filter: OverlapFilter | str = OverlapFilter.NON_MAX_SUPPRESSION,
        iou_threshold: float = 0.5,
        overlap_metric: OverlapMetric | str = OverlapMetric.IOU,
        thread_workers: int = 1,
        compact_masks: bool = False,
        batch_size: int = 1,
    ):
        slice_wh_norm = self._normalize_slice_wh(slice_wh)
        overlap_wh_norm = self._normalize_overlap_wh(overlap_wh)

        self._validate_overlap(slice_wh=slice_wh_norm, overlap_wh=overlap_wh_norm)

        if thread_workers < 1:
            raise ValueError(
                "`thread_workers` must be a positive integer. "
                f"Received: {thread_workers}"
            )
        if batch_size < 1:
            raise ValueError(
                f"`batch_size` must be a positive integer. Received: {batch_size}"
            )

        self.slice_wh = slice_wh_norm
        self.overlap_wh = overlap_wh_norm
        self.iou_threshold = iou_threshold
        self.overlap_metric = OverlapMetric.from_value(overlap_metric)
        self.overlap_filter = OverlapFilter.from_value(overlap_filter)
        # Stored as single-image type; batch path calls with list[ndarray] via
        # _run_callback_batch which suppresses the arg-type mismatch there.
        self.callback: Callable[[npt.NDArray[Any]], Detections] = callback  # type: ignore[assignment]
        self.thread_workers = thread_workers
        self.compact_masks = compact_masks
        self.batch_size = batch_size
        self._out_of_slice_bounds_warned: bool = False
        self._out_of_slice_bounds_lock = threading.Lock()
        self._obb_thread_workers_warned: bool = False
        self._obb_thread_workers_lock = threading.Lock()

View on GitHub (pinned to 7f254d9784)

Solutions

1. Use a positive integer, e.g. batch_size=4, or keep the default of 1 (one slice per callback call).
2. Clamp computed batch sizes: batch_size = max(1, computed).
3. Remember batch_size > 1 obligates the callback to accept a list of images and return a list of Detections.

Example fix

# before
slicer = sv.InferenceSlicer(callback=cb, batch_size=int(vram_mb // 2000))  # 0 on small GPUs

# after
slicer = sv.InferenceSlicer(callback=cb, batch_size=max(1, int(vram_mb // 2000)))

batch_size = max(1, int(cfg.get('batch_size', 1)) or 1)
slicer = sv.InferenceSlicer(callback=cb, batch_size=batch_size)

def is_valid_batch_size(v) -> bool:
    return isinstance(v, int) and v >= 1

When it happens

Trigger: Constructing sv.InferenceSlicer(callback=..., batch_size=0) or a negative value; deriving batch size from available VRAM with a formula that floors to 0.

Common situations: Auto-batching heuristics that compute max(0, vram // mb_per_slice); config defaults copied from APIs where 0 means 'auto'; CLI parsing that yields 0 when the flag is omitted.

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
• `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/693855ec154ada90. Report an issue: GitHub.