langchain-ai/deepagents · error · VideoExtractionError

No frames decoded for window [{offset_seconds:.3f}s, {end_se

Error message

No frames decoded for window [{offset_seconds:.3f}s, {end_seconds:.3f}s)

What it means

After decoding the requested window, if no frames were produced at all, extract_video_frames raises VideoExtractionError naming the window. This distinguishes 'seek/decode produced nothing' from other failures and prevents silently returning empty results.

Source

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

                    offset_seconds=offset_seconds,
                    duration_seconds=float(duration),
                    sampling_rate=rate,
                    time_base=time_base,
                    stream_start_seconds=stream_start_seconds,
                    deadline_seconds=time.monotonic() + MAX_VIDEO_DECODE_SECONDS,
                    decode_error_types=backend_error_types,
                )
            )
        except backend_error_types as exc:
            msg = f"Failed to decode video frames: {exc}"
            raise VideoExtractionError(msg) from exc
    finally:
        container.close()

    if not blocks:
        end_seconds = offset_seconds + duration
        msg = f"No frames decoded for window [{offset_seconds:.3f}s, {end_seconds:.3f}s)"
        raise VideoExtractionError(msg)
    return blocks


def _validate_video_window(*, offset_seconds: float, duration_seconds: float, sampling_rate: float) -> None:
    """Validate the requested sampling window before opening the video."""
    if offset_seconds < 0:
        msg = f"offset_seconds must be >= 0, got {offset_seconds!r}"
        raise ValueError(msg)
    if sampling_rate <= 0:
        msg = f"sampling_rate must be > 0, got {sampling_rate!r}"
        raise ValueError(msg)
    if duration_seconds <= 0:
        msg = f"duration_seconds must be > 0, got {duration_seconds!r}"
        raise ValueError(msg)


def _open_video_container(av: Any, content: bytes) -> Any:  # noqa: ANN401  # PyAV types are unavailable without the [video] extra
    """Open a video byte payload, normalizing PyAV's failure modes.

View on GitHub (pinned to a1af029e6e)

Solutions

Probe the video duration (ffprobe / container.duration) and clamp the window inside it.
Use offset_seconds=0 with a small duration to verify frames exist at all.
Correct unit conversions so the window is in seconds.
Catch VideoExtractionError and retry from the start of the video.

Example fix

// before
frames = extract_video_frames(content, offset_seconds=600.0, duration_seconds=5.0)  # 10s video
// after
duration = get_video_duration(content)
offset = min(600.0, max(0.0, duration - 1.0))
frames = extract_video_frames(content, offset_seconds=offset, duration_seconds=1.0)

Defensive patterns

Strategy: validation

Validate before calling

def window_inside_duration(offset_seconds: float, duration_seconds: float, media_duration: float) -> bool:
    return offset_seconds >= 0 and offset_seconds + duration_seconds <= media_duration and media_duration > 0

Try / catch

try:
    frames = extract_video_frames(content, offset_seconds=offset, duration_seconds=duration)
except VideoExtractionError as exc:
    if str(exc).startswith("No frames decoded"):
        frames = extract_video_frames(content, offset_seconds=0.0, duration_seconds=min(duration, media_duration))
    else:
        raise

Prevention

Read container.duration and clamp the requested window to [0, duration).
Never trust agent-guessed timestamps; derive them from probe metadata.
Fix unit conversions (ms vs s) in callers computing windows.
For short clips, default to a window starting at 0.

When it happens

Trigger: extract_video_frames with an offset_seconds beyond the end of the video, a video shorter than the requested offset, or streams that decode zero frames in the requested range.

Common situations: Requesting frames at 10 minutes of a 30-second clip; agents guessing timestamps; windows computed with wrong unit conversions (e.g. seconds-vs-milliseconds).

Related errors

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