langchain-ai/deepagents · error · VideoExtractionError

Video stream time_base is zero; cannot determine frame times

Error message

Video stream time_base is zero; cannot determine frame timestamps

What it means

A stream time_base of zero is mathematically unusable for timestamp conversion (division by zero), so extract_video_frames raises VideoExtractionError when float(video_stream.time_base) == 0.0.

Source

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

    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)
            if offset_seconds > 0:
                # `seek` keeps the math correct across containers that already sit
                # 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,
                )

View on GitHub (pinned to a1af029e6e)

Solutions

1. Re-encode or remux the file with ffmpeg to fix stream metadata.
2. Validate the video with ffprobe before extraction.
3. Replace the source file — the container metadata is corrupt.
4. Catch VideoExtractionError and skip/report the file as undecodable.

Example fix

// before
frames = extract_video_frames(corrupt_bytes)
// after
if ffprobe_reports_valid_timebase("clip.mp4"):
    frames = extract_video_frames(read("clip.mp4"))

def time_base_is_usable(stream) -> bool:
    tb = getattr(stream, "time_base", None)
    return tb is not None and float(tb) != 0.0

try:
    frames = extract_video_frames(content, offset_seconds=0, duration_seconds=5)
except VideoExtractionError as exc:
    if "time_base is zero" in str(exc):
        return {"error": "Video metadata is corrupt; re-encode the file with ffmpeg"}
    raise

When it happens

Trigger: extract_video_frames on a video whose stream reports time_base equal to zero — seen with corrupted files, degenerate container metadata, or synthetic streams from faulty encoders.

Common situations: Truncated or corrupted uploads; programmatically generated videos with incorrect timing metadata; storage/transcoding pipelines that mangled stream headers.

Related errors

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

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