langchain-ai/deepagents · error · VideoExtractionError

offset_seconds must be >= 0, got {offset_seconds!r}

Error message

offset_seconds must be >= 0, got {offset_seconds!r}

What it means

extract_video_frames validates the sampling window before opening the video. A negative offset_seconds is invalid (time before the start of the media), so the underlying ValueError from _validate_video_window is re-raised as VideoExtractionError.

Source

Thrown at libs/deepagents/deepagents/middleware/_video.py:152

    Returns:
        Interleaved content blocks: a text header introducing each frame
        followed by a JPEG `image` content block. Raw video bytes are never
        returned.

    Raises:
        VideoExtractionError: If PyAV cannot open the payload or the
            requested window yields no decodable frames, or if argument
            validation fails before opening the file.
    """
    try:
        _validate_video_window(
            offset_seconds=offset_seconds,
            duration_seconds=duration_seconds,
            sampling_rate=sampling_rate,
        )
    except ValueError as exc:
        raise VideoExtractionError(str(exc)) from exc
    rate = float(sampling_rate)
    duration = float(duration_seconds)

    av = _import_av()
    container = _open_video_container(av, content)
    backend_error_types = _video_backend_error_types(av)
    try:
        try:
            video_stream = _find_video_stream(container)
            raw_time_base = video_stream.time_base
            if raw_time_base is None:
                msg = "Video stream has no time_base; cannot determine frame timestamps"
                raise VideoExtractionError(msg)
            time_base = float(raw_time_base)
            if time_base == 0.0:
                msg = "Video stream time_base is zero; cannot determine frame timestamps"
                raise VideoExtractionError(msg)
            stream_start_seconds = _stream_start_seconds(video_stream, time_base)

View on GitHub (pinned to a1af029e6e)

Solutions

1. Clamp offset_seconds to 0: max(0, offset_seconds).
2. Compute offsets only from guaranteed non-negative timestamps.
3. Validate user/agent-provided offsets before calling.
4. Catch VideoExtractionError and retry with offset_seconds=0.

Example fix

// before
frames = extract_video_frames(content, offset_seconds=-2.0)
// after
frames = extract_video_frames(content, offset_seconds=max(0.0, offset_seconds))

def valid_window(offset_seconds: float, duration_seconds: float, sampling_rate: float) -> bool:
    return offset_seconds >= 0 and duration_seconds > 0 and sampling_rate > 0

def is_non_negative_number(v: object) -> bool:
    return isinstance(v, (int, float)) and not isinstance(v, bool) and v >= 0

try:
    frames = extract_video_frames(content, offset_seconds=offset)
except VideoExtractionError as exc:
    if "offset_seconds must be >= 0" in str(exc):
        frames = extract_video_frames(content, offset_seconds=0.0)
    else:
        raise

When it happens

Trigger: Calling extract_video_frames(offset_seconds=-5, ...) directly, or via a video read where the caller computed a negative offset (e.g. subtracting durations or misinterpreting 'seconds from end').

Common situations: LLM agents supplying negative offsets when asked to inspect the end of a clip; arithmetic errors computing window starts; UI inputs that arrive negative after conversion.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• thread_id must be non-empty
• sampling_rate must be > 0, got {sampling_rate!r}
• duration_seconds must be > 0, got {duration_seconds!r}
• cron retention window cannot be negative
• modes can only be provided when agent is a factory

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/522b8aeeda302311. Report an issue: GitHub.