langchain-ai/deepagents · error · VideoExtractionError

Video frame output exceeded the {MAX_VIDEO_EMITTED_BYTES} by

Error message

Video frame output exceeded the {MAX_VIDEO_EMITTED_BYTES} byte safety budget before emitting a frame

What it means

Extraction enforces a cumulative output budget of `MAX_VIDEO_EMITTED_BYTES`. If the very first frame block (text + base64 JPEG) already exceeds that budget, `_sample_frames_in_window` raises `VideoExtractionError` because emitting zero frames plus a truncation notice would be useless.

Source

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

            if frame_seconds is None:
                continue
            if frame_seconds >= end_seconds:
                break
            if frame_seconds + 1e-6 < next_emit_seconds:
                continue
            if emitted_frames >= MAX_VIDEO_SAMPLED_FRAMES:
                truncated = True
                break

            jpeg_bytes = _encode_jpeg(frame)
            image_base64 = base64.b64encode(jpeg_bytes)
            ts = _format_timestamp(frame_seconds)
            text = f"Frame at t={ts}"
            next_block_bytes = len(text.encode()) + len(image_base64)
            if emitted_bytes + next_block_bytes > MAX_VIDEO_EMITTED_BYTES:
                if emitted_frames == 0:
                    msg = f"Video frame output exceeded the {MAX_VIDEO_EMITTED_BYTES} byte safety budget before emitting a frame"
                    raise VideoExtractionError(msg)
                truncated = True
                break

            blocks.append({"type": "text", "text": text})
            blocks.append(
                {
                    "type": "image",
                    "base64": image_base64.decode("ascii"),
                    "mime_type": "image/jpeg",
                }
            )
            emitted_frames += 1
            emitted_bytes += next_block_bytes
            last_emitted_seconds = frame_seconds
            emitted_index = math.floor((frame_seconds - offset_seconds) / frame_interval_seconds) + 1
            next_emit_seconds = max(
                next_emit_seconds + frame_interval_seconds,
                offset_seconds + frame_interval_seconds * emitted_index,

View on GitHub (pinned to a1af029e6e)

Solutions

1. Lower the source resolution before extraction so each frame's base64 fits the budget
2. Use a smaller sampling window/rate to reduce frames (does not help if the first frame alone is too big — must shrink the frame itself)
3. Catch `VideoExtractionError` and handle the video without inline frames

Example fix

// before
frames = extract_video_frames(bytes_4k, offset_seconds=0, duration_seconds=10, sampling_rate=1)
// after
smaller = transcode_to_720p(bytes_4k)
frames = extract_video_frames(smaller, offset_seconds=0, duration_seconds=10, sampling_rate=1)

w, h = probe_dimensions(content)
estimated_frame_bytes = (w * h * 3) * 4 // 3  # rough base64 JPEG upper bound
if estimated_frame_bytes > MAX_VIDEO_EMITTED_BYTES:
    raise ValueError("frame too large for output budget; downscale first")

try:
    result = extract_video_frames(content, offset_seconds=0, duration_seconds=10, sampling_rate=1)
except VideoExtractionError as exc:
    if "byte safety budget" in str(exc):
        result = extract_video_frames(downscale_to_720p(content), offset_seconds=0, duration_seconds=10, sampling_rate=1)

When it happens

Trigger: Frames so large (high resolution -> big base64 JPEGs) that a single frame's block exceeds the total byte budget.

Common situations: 8K/4K source video with high JPEG quality; crafted videos meant to blow up context size; very low budget constant combined with huge frames.

Related errors

• Video frame dimensions {width}x{height} exceed the maximum {
• Video decoding exceeded the {MAX_VIDEO_DECODE_SECONDS:.1f}s
• Could not read rubric file {path!r}: {exc}.
• Reading video files requires the optional video dependencies
• offset_seconds must be >= 0, got {offset_seconds!r}

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