roboflow/supervision · error · ValueError

prefetch must be >= 0, got {prefetch}

Error message

prefetch must be >= 0, got {prefetch}

What it means

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.

Source

Thrown at src/supervision/utils/video.py:278

            cap.release()
        ```

    Examples:
        ```python
        import supervision as sv

        for frame in sv.get_video_frames_generator(source_path="<SOURCE_VIDEO_PATH>"):
            ...

        # Prefetch frames in a background thread to overlap I/O with CPU inference:
        for frame in sv.get_video_frames_generator(
            source_path="<SOURCE_VIDEO_PATH>", prefetch=8
        ):
            ...
        ```
    """
    if prefetch < 0:
        raise ValueError(f"prefetch must be >= 0, got {prefetch!r}")
    if prefetch > 0:
        yield from _prefetched_frames_generator(
            source_path=source_path,
            stride=stride,
            start=start,
            end=end,
            iterative_seek=iterative_seek,
            prefetch=prefetch,
        )
        return

    video, start, end = _validate_and_setup_video(
        source_path, start, end, iterative_seek
    )
    frame_position = start
    try:
        while True:
            success, frame = video.read()

View on GitHub (pinned to 7f254d9784)

Solutions

1. Use prefetch=0 if you want no background reading, or a positive count like 4-16.
2. Clamp computed values: prefetch=max(0, computed).
3. Validate config values at load time before passing them to the generator.

Example fix

// before
sv.get_video_frames_generator(path, prefetch=-1)

// after
sv.get_video_frames_generator(path, prefetch=0)  # synchronous reading

prefetch = max(0, int(prefetch))
sv.get_video_frames_generator(path, prefetch=prefetch)

When it happens

Trigger: 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.

Common situations: Tuning code that derives prefetch from throughput measurements; configuration files where a minus sign slips in; passing -1 intending 'no limit' (not supported).

Related errors

• resolution must be a tuple of two integers, got
• Both dimensions in resolution must be positive. Got ({w}, {h
• `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

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