langchain-ai/deepagents · error · VideoExtractionError

Reading video files requires the optional video dependencies

Error message

Reading video files requires the optional video dependencies. Install them with `uv add 'deepagents[video]'`. (underlying error: {exc})

What it means

Video frame extraction depends on the optional PyAV ('av') package. If 'av' is not installed, _import_av raises VideoExtractionError with install instructions (`uv add 'deepagents[video]'`) instead of an opaque ImportError.

Source

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

class VideoExtractionError(RuntimeError):
    """Raised when PyAV cannot produce frames for the requested window."""


def _import_av() -> Any:  # noqa: ANN401  # PyAV types are unavailable without the [video] extra
    """Import PyAV lazily so the dep stays optional.

    Returns:
        The imported `av` module.

    Raises:
        VideoExtractionError: If PyAV is not installed, with installation
            guidance in the message.
    """
    try:
        import av  # noqa: PLC0415 - lazy import keeps the extra optional
    except ImportError as exc:  # pragma: no cover - exercised only when `av` is absent
        msg = f"{MISSING_VIDEO_HINT} (underlying error: {exc})"
        raise VideoExtractionError(msg) from exc
    return av


def _format_timestamp(seconds: float) -> str:
    """Format a frame timestamp as `HH:MM:SS.mmm` for the text header block."""
    if seconds < 0:
        seconds = 0.0
    total_ms = round(seconds * 1000)
    hours, rem_ms = divmod(total_ms, 3_600_000)
    minutes, rem_ms = divmod(rem_ms, 60_000)
    secs, ms = divmod(rem_ms, 1000)
    return f"{hours:02d}:{minutes:02d}:{secs:02d}.{ms:03d}"


def extract_video_frames(
    content: bytes,
    *,
    offset_seconds: float,

View on GitHub (pinned to a1af029e6e)

Solutions

1. Install the extra: `uv add 'deepagents[video]'` (or `pip install 'deepagents[video]'`).
2. Install PyAV directly if the extra is unavailable: `pip install av`.
3. Ensure the deployment image includes the video extra.
4. Catch VideoExtractionError and return the install hint to the user/agent.

Example fix

// before
pip install deepagents
// after
pip install "deepagents[video]"

def av_available() -> bool:
    try:
        import av  # noqa: F401
        return True
    except ImportError:
        return False

def can_read_video(path: str) -> bool:
    return path.lower().endswith((".mp4", ".mov", ".webm", ".mkv")) and av_available()

try:
    blocks = read_video(path)
except VideoExtractionError as exc:
    if "deepagents[video]" in str(exc):
        return {"error": "Video support not installed. Run: pip install 'deepagents[video]'"}
    raise

When it happens

Trigger: Reading a video file through the middleware (_handle_video_read -> extract_video_frames -> _import_av) in an environment where the deepagents[video] extra was not installed.

Common situations: Deploying to a container/CI image built from the base package without extras; letting an agent read .mp4/.mov files in a minimal install; fresh virtualenv missing optional dependencies.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• offset_seconds must be >= 0, got {offset_seconds!r}
• Video stream has no time_base; cannot determine frame timest
• Video stream time_base is zero; cannot determine frame times
• Failed to decode video frames: {exc}
• No frames decoded for window [{offset_seconds:.3f}s, {end_se

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