{"record":{"id":"c237892c455ef28b","repo":"vllm-project/vllm","slug":"could-not-open-video-file-path","errorCode":null,"errorMessage":"Could not open video file {path}","messagePattern":"Could not open video file (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/assets/video.py","lineNumber":48,"sourceCode":"\n    video_path = video_directory / filename\n    video_path_str = str(video_path)\n    if not video_path.exists():\n        video_path_str = hf_api().hf_hub_download(\n            repo_id=\"raushan-testing-hf/videos-test\",\n            filename=filename,\n            repo_type=\"dataset\",\n            cache_dir=video_directory,\n        )\n    return video_path_str\n\n\ndef video_to_ndarrays(path: str, num_frames: int = -1) -> npt.NDArray:\n    import cv2\n\n    cap = cv2.VideoCapture(path)\n    if not cap.isOpened():\n        raise ValueError(f\"Could not open video file {path}\")\n\n    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))\n    frames = []\n\n    num_frames = num_frames if num_frames > 0 else total_frames\n    frame_indices = _sample_frame_indices(total_frames, num_frames)\n    for idx in range(total_frames):\n        ok = cap.grab()  # next img\n        if not ok:\n            break\n        if idx in frame_indices:  # only decompress needed\n            ret, frame = cap.retrieve()\n            if ret:\n                # OpenCV uses BGR format, we need to convert it to RGB\n                # for PIL and transformers compatibility\n                frames.append(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))\n\n    frames = np.stack(frames)","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/assets/video.py#L30-L66","documentation":"video_to_ndarrays() opens the file with cv2.VideoCapture and checks cap.isOpened(). OpenCV fails to open when the path does not exist, the file is unreadable/corrupt, or OpenCV's FFmpeg backend cannot handle the container/codec. vLLM raises ValueError naming the path so the caller knows the video never loaded.","triggerScenarios":"Calling vllm.assets.video.video_to_ndarrays(path) with a nonexistent/wrong path, an unsupported codec build of cv2 (pip opencv-python without FFmpeg), a corrupt/truncated download, or a remote URL where the file was not downloaded first.","commonSituations":"Multimodal video inputs with an incorrect path in the request; a cached HF dataset download that was interrupted; an opencv-python-headless build lacking codec support for the video format.","solutions":["Verify the path exists and is a real file (os.path.isfile) and that ffprobe/ffmpeg or cv2 can open it independently","Use the provided fetch_video helper (hf_hub_download based) to guarantee a fully downloaded local file instead of hand-building paths","Upgrade/reinstall opencv-python (non-headless or with FFmpeg support) if the codec is the problem"],"exampleFix":"# before\nframes = video_to_ndarrays(\"/data/clip.mp4\")  # typo'd/corrupt path\n# after\nfrom vllm.assets.video import fetch_video\npath = fetch_video(\"/data/clip.mp4\")\nassert os.path.isfile(path)\nframes = video_to_ndarrays(path)","handlingStrategy":"validation","validationCode":"import os\nif not os.path.isfile(path):\n    raise FileNotFoundError(path)\nimport cv2\ncap = cv2.VideoCapture(path)\nok = cap.isOpened(); cap.release()\nassert ok, f\"cv2 cannot open {path}\"","typeGuard":null,"tryCatchPattern":"try:\n    frames = video_to_ndarrays(path, num_frames)\nexcept ValueError as e:\n    if \"Could not open\" in str(e):\n        raise UserInputError(f\"bad video: {path}\") from e\n    raise","preventionTips":["Validate user-supplied video paths and probe with cv2 before batch jobs","Use fetch_video to materialize a complete local file first"],"tags":["video","multimodal","opencv","file-io","validation"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}