microsoft/autogen · warning · ValueError

Timestamp {timestamp:.2f}s is out of range [0s, {duration:.2

Error message

Timestamp {timestamp:.2f}s is out of range [0s, {duration:.2f}s]

What it means

get_screenshots() computes duration = total_frames / fps and raises ValueError for any timestamp outside [0, duration] (inclusive). This is intentional input validation before seeking — OpenCV seeking outside the stream either fails or misbehaves, so the tool rejects the request outright. Note fps can be 0.0 for broken streams, making duration inf/NaN and validation unreliable.

Source

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

    if not cap.isOpened():
        raise IOError(f"Cannot open video file {video_path}")

    fps = cap.get(cv2.CAP_PROP_FPS)
    total_frames = cap.get(cv2.CAP_PROP_FRAME_COUNT)
    duration = total_frames / fps

    for timestamp in timestamps:
        if 0 <= timestamp <= duration:
            frame_number = int(timestamp * fps)
            cap.set(cv2.CAP_PROP_POS_FRAMES, frame_number)
            ret, frame = cap.read()
            if ret:
                # Append the timestamp and frame to the list
                screenshots.append((timestamp, frame))
            else:
                raise IOError(f"Failed to capture frame at {timestamp:.2f}s")
        else:
            raise ValueError(f"Timestamp {timestamp:.2f}s is out of range [0s, {duration:.2f}s]")

    cap.release()
    return screenshots

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Call get_video_length(video_path) first and clamp timestamps into [0, duration]
2. Filter: timestamps = [t for t in timestamps if 0 <= t <= duration]
3. Ensure timestamps are in seconds, not milliseconds
4. Guard against fps == 0 (corrupt stream) by re-encoding the source video

Example fix

// before
shots = get_screenshots(video, [0, 500, 900])  # ms mistaken for s -> ValueError

// after
shots = get_screenshots(video, [t / 1000.0 for t in (0, 500, 900)])  # seconds

import re
from autogen_ext.agents.video_surfer.tools import get_video_length
def valid_timestamps(video: str, ts_list: list[float]) -> list[float]:
    dur = float(re.search(r'[\d.]+', get_video_length(video)).group())
    return [t for t in ts_list if 0.0 <= t <= dur]

try:
    shots = get_screenshots(video, timestamps)
except ValueError as e:
    if 'out of range' in str(e):
        timestamps = valid_timestamps(video, timestamps)
        shots = get_screenshots(video, timestamps)
    else:
        raise

When it happens

Trigger: Passing a negative timestamp, a timestamp larger than the video length (e.g. asking for 60s on a 30s clip), or timestamps derived from a different video or from hallucinated LLM output.

Common situations: Agents guessing timestamps without first calling get_video_length(), unit conversions (milliseconds passed as seconds), mixed-up files in a processing queue.

Related errors

• Cannot open video file {video_path}
• Failed to capture frame at {timestamp:.2f}s
• audio_output_path must end with .mp3.
• audio_output_path must be within the current working directo
• Failed to list MCP prompts

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