{"record":{"id":"693855ec154ada90","repo":"roboflow/supervision","slug":"batch-size-must-be-a-positive-integer-received","errorCode":null,"errorMessage":"`batch_size` must be a positive integer. Received: {batch_size}","messagePattern":"`batch_size` must be a positive integer\\. Received: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/detection/tools/inference_slicer.py","lineNumber":288,"sourceCode":"        overlap_filter: OverlapFilter | str = OverlapFilter.NON_MAX_SUPPRESSION,\n        iou_threshold: float = 0.5,\n        overlap_metric: OverlapMetric | str = OverlapMetric.IOU,\n        thread_workers: int = 1,\n        compact_masks: bool = False,\n        batch_size: int = 1,\n    ):\n        slice_wh_norm = self._normalize_slice_wh(slice_wh)\n        overlap_wh_norm = self._normalize_overlap_wh(overlap_wh)\n\n        self._validate_overlap(slice_wh=slice_wh_norm, overlap_wh=overlap_wh_norm)\n\n        if thread_workers < 1:\n            raise ValueError(\n                \"`thread_workers` must be a positive integer. \"\n                f\"Received: {thread_workers}\"\n            )\n        if batch_size < 1:\n            raise ValueError(\n                f\"`batch_size` must be a positive integer. Received: {batch_size}\"\n            )\n\n        self.slice_wh = slice_wh_norm\n        self.overlap_wh = overlap_wh_norm\n        self.iou_threshold = iou_threshold\n        self.overlap_metric = OverlapMetric.from_value(overlap_metric)\n        self.overlap_filter = OverlapFilter.from_value(overlap_filter)\n        # Stored as single-image type; batch path calls with list[ndarray] via\n        # _run_callback_batch which suppresses the arg-type mismatch there.\n        self.callback: Callable[[npt.NDArray[Any]], Detections] = callback  # type: ignore[assignment]\n        self.thread_workers = thread_workers\n        self.compact_masks = compact_masks\n        self.batch_size = batch_size\n        self._out_of_slice_bounds_warned: bool = False\n        self._out_of_slice_bounds_lock = threading.Lock()\n        self._obb_thread_workers_warned: bool = False\n        self._obb_thread_workers_lock = threading.Lock()","sourceCodeStart":270,"sourceCodeEnd":306,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/detection/tools/inference_slicer.py#L270-L306","documentation":"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.","triggerScenarios":"Constructing sv.InferenceSlicer(callback=..., batch_size=0) or a negative value; deriving batch size from available VRAM with a formula that floors to 0.","commonSituations":"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.","solutions":["Use a positive integer, e.g. batch_size=4, or keep the default of 1 (one slice per callback call).","Clamp computed batch sizes: batch_size = max(1, computed).","Remember batch_size > 1 obligates the callback to accept a list of images and return a list of Detections."],"exampleFix":"# before\nslicer = sv.InferenceSlicer(callback=cb, batch_size=int(vram_mb // 2000))  # 0 on small GPUs\n\n# after\nslicer = sv.InferenceSlicer(callback=cb, batch_size=max(1, int(vram_mb // 2000)))","handlingStrategy":"validation","validationCode":"batch_size = max(1, int(cfg.get('batch_size', 1)) or 1)\nslicer = sv.InferenceSlicer(callback=cb, batch_size=batch_size)","typeGuard":"def is_valid_batch_size(v) -> bool:\n    return isinstance(v, int) and v >= 1","tryCatchPattern":null,"preventionTips":["Clamp VRAM-derived batch sizes with max(1, ...).","When raising batch_size above 1, update the callback contract at the same time."],"tags":["inference-slicer","batching","configuration","validation","valueerror"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}