langchain-ai/deepagents · error · VideoExtractionError

Video frame dimensions {width}x{height} exceed the maximum {

Error message

Video frame dimensions {width}x{height} exceed the maximum {MAX_VIDEO_FRAME_SIDE}px side

What it means

`_validate_dimensions`, invoked during JPEG encoding, rejects any frame whose width or height exceeds `MAX_VIDEO_FRAME_SIDE`. Guarding before conversion prevents allocating enormous images (memory exhaustion / decompression bombs) from hostile or 8K+ sources.

Source

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

    return None


def _frame_dimensions(frame: Any) -> tuple[int, int] | None:  # noqa: ANN401  # PyAV types are unavailable without the [video] extra
    """Return frame dimensions when the decoder exposes them."""
    width = getattr(frame, "width", None)
    height = getattr(frame, "height", None)
    if width is None or height is None:
        return None
    return int(width), int(height)


def _validate_dimensions(width: int, height: int) -> None:
    """Reject frame dimensions that are too large to safely convert."""
    if width <= 0 or height <= 0:
        return
    if width > MAX_VIDEO_FRAME_SIDE or height > MAX_VIDEO_FRAME_SIDE:
        msg = f"Video frame dimensions {width}x{height} exceed the maximum {MAX_VIDEO_FRAME_SIDE}px side"
        raise VideoExtractionError(msg)


def _check_decode_deadline(deadline_seconds: float | None) -> None:
    """Raise when best-effort video decoding has exceeded its time budget."""
    if deadline_seconds is not None and time.monotonic() > deadline_seconds:
        msg = f"Video decoding exceeded the {MAX_VIDEO_DECODE_SECONDS:.1f}s safety budget"
        raise VideoExtractionError(msg)


def _sample_frames_in_window(
    decoded_frames: Any,  # noqa: ANN401  # PyAV types are unavailable without the [video] extra
    *,
    offset_seconds: float,
    duration_seconds: float,
    sampling_rate: float,
    time_base: float,
    stream_start_seconds: float = 0.0,
    deadline_seconds: float | None = None,

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pre-scale/downsample the source video before extraction (ffmpeg -vf scale=...)
2. Catch `VideoExtractionError` and reject oversized inputs with a clear user message
3. Check the source resolution ahead of time and skip videos exceeding the limit

Example fix

// before
frames = extract_video_frames(huge_8k_bytes, offset_seconds=0, duration_seconds=10, sampling_rate=1)
// after
sub = subprocess.run(["ffmpeg", "-i", "in.mp4", "-vf", "scale=3840:-2", "out.mp4"])
frames = extract_video_frames(scaled_bytes, offset_seconds=0, duration_seconds=10, sampling_rate=1)

import av
with av.open(io.BytesIO(content)) as c:
    stream = next(s for s in c.streams if s.type == "video")
    w, h = stream.codec_context.width, stream.codec_context.height
    if w > MAX_VIDEO_FRAME_SIDE or h > MAX_VIDEO_FRAME_SIDE:
        raise ValueError(f"source resolution {w}x{h} too large")

def dimensions_ok(width: int, height: int, max_side: int = MAX_VIDEO_FRAME_SIDE) -> bool:
    return 0 < width <= max_side and 0 < height <= max_side

try:
    result = extract_video_frames(content, offset_seconds=0, duration_seconds=10, sampling_rate=1)
except VideoExtractionError as exc:
    if "exceed the maximum" in str(exc):
        content = downscale_video(content)
        result = extract_video_frames(content, offset_seconds=0, duration_seconds=10, sampling_rate=1)

When it happens

Trigger: Extracting frames from very high-resolution video (e.g. 8K, or crafted small files with huge frame dimensions) so a decoded frame's side exceeds the max allowed px.

Common situations: User-uploaded 7680x4320 footage; adversarial inputs designed to blow up memory; unexpected orientation metadata producing oversized frames.

Related errors

• Video decoding exceeded the {MAX_VIDEO_DECODE_SECONDS:.1f}s
• Video frame output exceeded the {MAX_VIDEO_EMITTED_BYTES} by
• debug log directory is not a real directory: {path}
• debug log directory is not owned by the current user: {path}
• Cannot determine whether {str(left)!r} is {str(right)!r}: {e

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