{"record":{"id":"243532608754a110","repo":"roboflow/supervision","slug":"could-not-open-video-at-source-path","errorCode":null,"errorMessage":"Could not open video at {source_path}","messagePattern":"Could not open video at (.+?)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"critical","filePath":"src/supervision/utils/video.py","lineNumber":175,"sourceCode":"\n    def __exit__(\n        self,\n        exc_type: type[BaseException] | None,\n        exc_value: BaseException | None,\n        exc_traceback: TracebackType | None,\n    ) -> None:\n        \"\"\"Release the underlying video writer when leaving the context.\"\"\"\n        if self.__writer is not None:\n            self.__writer.release()\n            self.__writer = None\n\n\ndef _validate_and_setup_video(\n    source_path: str, start: int, end: int | None, iterative_seek: bool = False\n) -> tuple[cv2.VideoCapture, int, int]:\n    video = cv2.VideoCapture(source_path)\n    if not video.isOpened():\n        raise Exception(f\"Could not open video at {source_path}\")\n    total_frames = int(video.get(cv2.CAP_PROP_FRAME_COUNT))\n    if end is not None and end > total_frames:\n        raise Exception(\"Requested frames are outbound\")\n    start = max(start, 0)\n    end = min(end, total_frames) if end is not None else total_frames\n\n    if iterative_seek:\n        while start > 0:\n            success = video.grab()\n            if not success:\n                break\n            start -= 1\n    elif start > 0:\n        video.set(cv2.CAP_PROP_POS_FRAMES, start)\n\n    return video, start, end\n\n","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/utils/video.py#L157-L193","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the path exists and is absolute: os.path.abspath(source_path), check os.path.isfile.","Sanity-check the file opens elsewhere: cv2.VideoCapture(path).isOpened() in a REPL, or ffprobe the file.","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.","Check file permissions and that the file is not being written by another process."],"exampleFix":"// before\nfor frame in sv.get_video_frames_generator(source_path='input.mp4'):  # wrong cwd\n\n// after\nsrc = os.path.abspath('videos/input.mp4')\nassert os.path.isfile(src), f'missing: {src}'\nfor frame in sv.get_video_frames_generator(source_path=src):","handlingStrategy":"validation","validationCode":"source_path = os.path.abspath(source_path)\nif not os.path.isfile(source_path):\n    raise FileNotFoundError(source_path)\nprobe = cv2.VideoCapture(source_path)\nif not probe.isOpened():\n    raise RuntimeError(f'OpenCV cannot decode {source_path}')\nprobe.release()\n# safe to iterate now","typeGuard":null,"tryCatchPattern":"try:\n    for frame in sv.get_video_frames_generator(path):\n        ...\nexcept Exception as e:\n    if 'Could not open video' in str(e):\n        log.error('bad or unreadable video: %s', path)\n        continue  # skip file in batch jobs\n    raise","preventionTips":["Resolve video paths to absolute paths at script start.","Probe with cv2.VideoCapture(path).isOpened() before processing batches.","Verify files with ffprobe when codecs are in doubt; standardize inputs to H.264 mp4."],"tags":["video","opencv","file-io","path"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}