microsoft/autogen · error · IOError

Cannot open video file {video_path}

Error message

Cannot open video file {video_path}

What it means

get_video_length() creates a cv2.VideoCapture for video_path and raises IOError when cap.isOpened() returns False, meaning OpenCV could not open the file at all. Typical root causes are a nonexistent/unreadable path, an unsupported container/codec, or an OpenCV build without the required video I/O backend (e.g. opencv-python-headless installed without ffmpeg support).

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/agents/video_surfer/tools.py:75

    for segment in segments:
        start: float = segment["start"]
        end: float = segment["end"]
        text: str = segment["text"]
        transcription_with_timestamps += f"[{start:.2f} - {end:.2f}] {text}\n"

    return transcription_with_timestamps


def get_video_length(video_path: str) -> str:
    """
    Returns the length of the video in seconds.

    :param video_path: Path to the video file.
    :return: Duration of the video in seconds.
    """
    cap = cv2.VideoCapture(video_path)
    if not cap.isOpened():
        raise IOError(f"Cannot open video file {video_path}")
    fps = cap.get(cv2.CAP_PROP_FPS)
    frame_count = cap.get(cv2.CAP_PROP_FRAME_COUNT)
    duration = frame_count / fps
    cap.release()

    return f"The video is {duration:.2f} seconds long."


def save_screenshot(video_path: str, timestamp: float, output_path: str) -> None:
    """
    Captures a screenshot at the specified timestamp and saves it to the output path.

    :param video_path: Path to the video file.
    :param timestamp: Timestamp in seconds.
    :param output_path: Path to save the screenshot. The file format is determined by the extension in the path.
    """
    cap = cv2.VideoCapture(video_path)
    if not cap.isOpened():

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Verify the file exists and is readable before calling: os.path.isfile(video_path)
2. Confirm the path is a local file, not a URL; download it first if needed
3. Install full OpenCV with video support: pip install opencv-python (not a build stripped of ffmpeg)
4. On Linux containers install system ffmpeg/libsm6/libxext6 and gstreamer plugins, or verify the codec with ffprobe video.mp4

Example fix

// before
length = get_video_length('/downloads/clip.mp4')  # may not exist yet

// after
import os
if not os.path.isfile(path):
    raise FileNotFoundError(path)
length = get_video_length(path)

import os, cv2
def can_open_video(p: str) -> bool:
    if not os.path.isfile(p):
        return False
    cap = cv2.VideoCapture(p)
    ok = cap.isOpened()
    cap.release()
    return ok

try:
    length = get_video_length(path)
except IOError as e:
    if not os.path.isfile(path):
        raise FileNotFoundError(path) from e
    raise RuntimeError(f'OpenCV cannot decode {path}; check codecs/backend: {e}') from e

When it happens

Trigger: Calling get_video_length('missing.mp4'), passing a directory or URL instead of a local file, a video encoded with a codec the installed OpenCV build cannot decode, or running in a slim container where libffmpeg/gstreamer backend libraries are absent.

Common situations: Agent workflows where the LLM hallucinates a video filename, downloading a video to a path different from the one passed in, Docker images based on python:*-slim without ffmpeg/codec system libraries, or corrupted/incomplete downloads.

Related errors

• Failed to capture frame at {timestamp:.2f}s
• Timestamp {timestamp:.2f}s is out of range [0s, {duration:.2
• Could not find directory for assembly '{asm}'.
• video_path must be a local file path, not a URL.
• audio_output_path must end with .mp3.

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/28b5b755bea56c01. Report an issue: GitHub.