langchain-ai/deepagents · error · VideoExtractionError

Failed to decode video frames: {exc}

Error message

Failed to decode video frames: {exc}

What it means

The PyAV decoder raised an error while decoding frames in the requested window (codec/container decode failure). extract_video_frames catches backend error types and re-raises them as VideoExtractionError with the underlying message.

Source

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

                # at a non-zero timeline (e.g. trimmed clips).
                start_pts = _stream_start_pts(video_stream) + int(offset_seconds / time_base)
                container.seek(start_pts, any_frame=False, backward=True, stream=video_stream)

            blocks = list(
                _sample_frames_in_window(
                    container.decode(video_stream),
                    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)

View on GitHub (pinned to a1af029e6e)

Solutions

1. Re-encode the video to H.264 with ffmpeg: `ffmpeg -i in.mov -c:v libx264 -c:a aac out.mp4`.
2. Upgrade av/PyAV (and its bundled FFmpeg): `pip install -U av`.
3. Check whether the stream is encrypted/DRM-protected; obtain a decodable copy.
4. Catch VideoExtractionError, log the underlying decode error, and degrade gracefully.

Example fix

// before
frames = extract_video_frames(hevc_bytes)  # codec not supported
// after
subprocess.run(["ffmpeg", "-y", "-i", "in.mp4", "-c:v", "libx264", "out.mp4"])
frames = extract_video_frames(open("out.mp4", "rb").read())

def probe_decodable(path: str) -> bool:
    import subprocess
    r = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v", path], capture_output=True)
    return r.returncode == 0 and r.stdout != b""

try:
    frames = extract_video_frames(content, offset_seconds=0, duration_seconds=10)
except VideoExtractionError as exc:
    if str(exc).startswith("Failed to decode video frames"):
        transcoded = transcode_to_h264(content)
        frames = extract_video_frames(transcoded, offset_seconds=0, duration_seconds=10)
    else:
        raise

When it happens

Trigger: extract_video_frames on a video with a codec the installed PyAV/FFmpeg build cannot decode, corrupted frames in the seek window, or DRM/encrypted streams.

Common situations: Missing FFmpeg codecs for HEVC/AV1/ProRes in the environment; corrupted or partially downloaded media; encrypted commercial streams.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to open video payload: {exc}
• Video stream has no time_base; cannot determine frame timest
• Video stream time_base is zero; cannot determine frame times
• No frames decoded for window [{offset_seconds:.3f}s, {end_se
• Video payload contains no video stream

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