langchain-ai/deepagents · error · ValueError

sampling_rate must be > 0, got {sampling_rate!r}

Error message

sampling_rate must be > 0, got {sampling_rate!r}

What it means

`_validate_video_window` requires a strictly positive `sampling_rate` (frames per second to sample). A zero or negative rate would make the frame interval undefined or backwards, so the library raises ValueError before decoding.

Source

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

            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.

    PyAV typically raises `av.error.InvalidDataError` for malformed inputs,
    but it falls back to `OSError` when the system ffmpeg library is missing
    or incompatible. Both surface to callers as `VideoExtractionError` so
    the middleware does not have to distinguish between them.
    """
    try:
        return av.open(io.BytesIO(content))
    except _video_backend_error_types(av) as exc:  # pragma: no cover - depends on host/input
        msg = f"Failed to open video payload: {exc}"
        raise VideoExtractionError(msg) from exc

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pass a positive `sampling_rate` (e.g. 1.0 for one frame per second)
2. Check the config/default path that supplied 0
3. Guard with `max(0.1, sampling_rate)` or reject bad config at load time

Example fix

// before
extract_video_frames(content, sampling_rate=settings.fps)  # settings.fps == 0
// after
if settings.fps <= 0:
    raise ValueError(f"configured sampling_rate must be > 0, got {settings.fps}")
extract_video_frames(content, sampling_rate=settings.fps)

if sampling_rate <= 0:
    raise ValueError(f"sampling_rate must be > 0, got {sampling_rate!r}")

def is_valid_sampling_rate(rate: float) -> bool:
    return isinstance(rate, (int, float)) and rate > 0

When it happens

Trigger: Calling `extract_video_frames` with `sampling_rate=0`, a negative value, or a 0.0 produced by a failed config lookup / division.

Common situations: Config file with sampling_rate missing and defaulting to 0; computing fps from metadata that returned 0; sign error in a formula.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• duration_seconds must be > 0, got {duration_seconds!r}
• modes can only be provided when agent is a factory
• models can only be provided when agent is a factory
• -32602
• recursion_limit must be None or a positive integer

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