vllm-project/vllm · error · ValueError

Could not open video file {path}

Error message

Could not open video file {path}

What it means

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.

Source

Thrown at vllm/assets/video.py:48

    video_path = video_directory / filename
    video_path_str = str(video_path)
    if not video_path.exists():
        video_path_str = hf_api().hf_hub_download(
            repo_id="raushan-testing-hf/videos-test",
            filename=filename,
            repo_type="dataset",
            cache_dir=video_directory,
        )
    return video_path_str


def video_to_ndarrays(path: str, num_frames: int = -1) -> npt.NDArray:
    import cv2

    cap = cv2.VideoCapture(path)
    if not cap.isOpened():
        raise ValueError(f"Could not open video file {path}")

    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
    frames = []

    num_frames = num_frames if num_frames > 0 else total_frames
    frame_indices = _sample_frame_indices(total_frames, num_frames)
    for idx in range(total_frames):
        ok = cap.grab()  # next img
        if not ok:
            break
        if idx in frame_indices:  # only decompress needed
            ret, frame = cap.retrieve()
            if ret:
                # OpenCV uses BGR format, we need to convert it to RGB
                # for PIL and transformers compatibility
                frames.append(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))

    frames = np.stack(frames)

View on GitHub (pinned to c794754062)

Solutions

1. Verify the path exists and is a real file (os.path.isfile) and that ffprobe/ffmpeg or cv2 can open it independently
2. Use the provided fetch_video helper (hf_hub_download based) to guarantee a fully downloaded local file instead of hand-building paths
3. Upgrade/reinstall opencv-python (non-headless or with FFmpeg support) if the codec is the problem

Example fix

# before
frames = video_to_ndarrays("/data/clip.mp4")  # typo'd/corrupt path
# after
from vllm.assets.video import fetch_video
path = fetch_video("/data/clip.mp4")
assert os.path.isfile(path)
frames = video_to_ndarrays(path)

import os
if not os.path.isfile(path):
    raise FileNotFoundError(path)
import cv2
cap = cv2.VideoCapture(path)
ok = cap.isOpened(); cap.release()
assert ok, f"cv2 cannot open {path}"

try:
    frames = video_to_ndarrays(path, num_frames)
except ValueError as e:
    if "Could not open" in str(e):
        raise UserInputError(f"bad video: {path}") from e
    raise

When it happens

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

Common situations: 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.

Related errors

• Could not read enough frames from video file {path} (expecte
• 'mm_shm_cache_max_object_size_mb' should only be set when 'm
• 'mm_encoder_fp8_scale_path' and 'mm_encoder_fp8_scale_save_p
• 'mm_encoder_fp8_scale_save_path' cannot be used with 'mm_enc
• Invalid "device" in mm_processor_kwargs: {device!r}. Expecte

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/c237892c455ef28b. Report an issue: GitHub.