{"record":{"id":"beffc139b8917058","repo":"roboflow/supervision","slug":"prefetch-must-be-0-got-prefetch","errorCode":null,"errorMessage":"prefetch must be >= 0, got {prefetch}","messagePattern":"prefetch must be >= 0, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/utils/video.py","lineNumber":278,"sourceCode":"            cap.release()\n        ```\n\n    Examples:\n        ```python\n        import supervision as sv\n\n        for frame in sv.get_video_frames_generator(source_path=\"<SOURCE_VIDEO_PATH>\"):\n            ...\n\n        # Prefetch frames in a background thread to overlap I/O with CPU inference:\n        for frame in sv.get_video_frames_generator(\n            source_path=\"<SOURCE_VIDEO_PATH>\", prefetch=8\n        ):\n            ...\n        ```\n    \"\"\"\n    if prefetch < 0:\n        raise ValueError(f\"prefetch must be >= 0, got {prefetch!r}\")\n    if prefetch > 0:\n        yield from _prefetched_frames_generator(\n            source_path=source_path,\n            stride=stride,\n            start=start,\n            end=end,\n            iterative_seek=iterative_seek,\n            prefetch=prefetch,\n        )\n        return\n\n    video, start, end = _validate_and_setup_video(\n        source_path, start, end, iterative_seek\n    )\n    frame_position = start\n    try:\n        while True:\n            success, frame = video.read()","sourceCodeStart":260,"sourceCodeEnd":296,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/utils/video.py#L260-L296","documentation":"Raised by get_video_frames_generator() in supervision.utils.video when the `prefetch` argument is negative. Prefetch controls how many frames a background reader thread may buffer ahead (0 disables it); negative values are meaningless and rejected up front with a clear ValueError.","triggerScenarios":"Calling sv.get_video_frames_generator(path, prefetch=-1); computing prefetch from a variable that can go negative, e.g. prefetch=batch_size-latency where latency > batch_size; typos like prefetch=-8 instead of 8.","commonSituations":"Tuning code that derives prefetch from throughput measurements; configuration files where a minus sign slips in; passing -1 intending 'no limit' (not supported).","solutions":["Use prefetch=0 if you want no background reading, or a positive count like 4-16.","Clamp computed values: prefetch=max(0, computed).","Validate config values at load time before passing them to the generator."],"exampleFix":"// before\nsv.get_video_frames_generator(path, prefetch=-1)\n\n// after\nsv.get_video_frames_generator(path, prefetch=0)  # synchronous reading","handlingStrategy":"validation","validationCode":"prefetch = max(0, int(prefetch))\nsv.get_video_frames_generator(path, prefetch=prefetch)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Clamp tuning parameters derived from measurements: prefetch = max(0, computed).","Validate numeric config values at load time."],"tags":["video","validation","configuration"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}