roboflow/supervision · critical · Exception

Could not open video at {source_path}

Error message

Could not open video at {source_path}

What it means

Raised by _validate_and_setup_video() in supervision.utils.video when cv2.VideoCapture cannot open the file at source_path (isOpened() returns False). This internal helper backs get_video_frames_generator and related frame-iteration APIs. Common root causes are a wrong path, an unreadable/corrupt file, or a missing OpenCV codec backend.

Source

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

    def __exit__(
        self,
        exc_type: type[BaseException] | None,
        exc_value: BaseException | None,
        exc_traceback: TracebackType | None,
    ) -> None:
        """Release the underlying video writer when leaving the context."""
        if self.__writer is not None:
            self.__writer.release()
            self.__writer = None


def _validate_and_setup_video(
    source_path: str, start: int, end: int | None, iterative_seek: bool = False
) -> tuple[cv2.VideoCapture, int, int]:
    video = cv2.VideoCapture(source_path)
    if not video.isOpened():
        raise Exception(f"Could not open video at {source_path}")
    total_frames = int(video.get(cv2.CAP_PROP_FRAME_COUNT))
    if end is not None and end > total_frames:
        raise Exception("Requested frames are outbound")
    start = max(start, 0)
    end = min(end, total_frames) if end is not None else total_frames

    if iterative_seek:
        while start > 0:
            success = video.grab()
            if not success:
                break
            start -= 1
    elif start > 0:
        video.set(cv2.CAP_PROP_POS_FRAMES, start)

    return video, start, end

View on GitHub (pinned to 7f254d9784)

Solutions

1. Verify the path exists and is absolute: os.path.abspath(source_path), check os.path.isfile.
2. Sanity-check the file opens elsewhere: cv2.VideoCapture(path).isOpened() in a REPL, or ffprobe the file.
3. If the codec is the issue, reinstall opencv with ffmpeg support (pip install opencv-python) or re-encode: ffmpeg -i in.mkv -c:v libx264 out.mp4.
4. Check file permissions and that the file is not being written by another process.

Example fix

// before
for frame in sv.get_video_frames_generator(source_path='input.mp4'):  # wrong cwd

// after
src = os.path.abspath('videos/input.mp4')
assert os.path.isfile(src), f'missing: {src}'
for frame in sv.get_video_frames_generator(source_path=src):

source_path = os.path.abspath(source_path)
if not os.path.isfile(source_path):
    raise FileNotFoundError(source_path)
probe = cv2.VideoCapture(source_path)
if not probe.isOpened():
    raise RuntimeError(f'OpenCV cannot decode {source_path}')
probe.release()
# safe to iterate now

try:
    for frame in sv.get_video_frames_generator(path):
        ...
except Exception as e:
    if 'Could not open video' in str(e):
        log.error('bad or unreadable video: %s', path)
        continue  # skip file in batch jobs
    raise

When it happens

Trigger: Calling sv.get_video_frames_generator(source_path='missing.mp4'); passing a relative path resolved against a different working directory; passing a URL scheme OpenCV cannot handle; the file existing but with zero permissions or truncated headers.

Common situations: Notebook/tutorial runs with placeholder paths like <SOURCE_VIDEO_PATH> not replaced; scripts run from another cwd where the relative path breaks; videos recorded incompletely (process killed mid-write); proprietary codecs needing ffmpeg-backed opencv.

Related errors

• Could not open video at {video_path}
• Could not open video writer for {self.target_path}
• Could not read image from path: {image_path}
• Requested frames are outbound
• Reader thread raised: {item}

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