{"record":{"id":"5a20068e07a61353","repo":"langchain-ai/deepagents","slug":"reading-video-files-requires-the-optional-video-de","errorCode":null,"errorMessage":"Reading video files requires the optional video dependencies. Install them with `uv add 'deepagents[video]'`. (underlying error: {exc})","messagePattern":"Reading video files requires the optional video dependencies\\. Install them with `uv add 'deepagents\\[video\\]'`\\. \\(underlying error: (.+?)\\)","errorType":"exception","errorClass":"VideoExtractionError","httpStatus":null,"severity":"error","filePath":"libs/deepagents/deepagents/middleware/_video.py","lineNumber":104,"sourceCode":"class VideoExtractionError(RuntimeError):\n    \"\"\"Raised when PyAV cannot produce frames for the requested window.\"\"\"\n\n\ndef _import_av() -> Any:  # noqa: ANN401  # PyAV types are unavailable without the [video] extra\n    \"\"\"Import PyAV lazily so the dep stays optional.\n\n    Returns:\n        The imported `av` module.\n\n    Raises:\n        VideoExtractionError: If PyAV is not installed, with installation\n            guidance in the message.\n    \"\"\"\n    try:\n        import av  # noqa: PLC0415 - lazy import keeps the extra optional\n    except ImportError as exc:  # pragma: no cover - exercised only when `av` is absent\n        msg = f\"{MISSING_VIDEO_HINT} (underlying error: {exc})\"\n        raise VideoExtractionError(msg) from exc\n    return av\n\n\ndef _format_timestamp(seconds: float) -> str:\n    \"\"\"Format a frame timestamp as `HH:MM:SS.mmm` for the text header block.\"\"\"\n    if seconds < 0:\n        seconds = 0.0\n    total_ms = round(seconds * 1000)\n    hours, rem_ms = divmod(total_ms, 3_600_000)\n    minutes, rem_ms = divmod(rem_ms, 60_000)\n    secs, ms = divmod(rem_ms, 1000)\n    return f\"{hours:02d}:{minutes:02d}:{secs:02d}.{ms:03d}\"\n\n\ndef extract_video_frames(\n    content: bytes,\n    *,\n    offset_seconds: float,","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/deepagents/deepagents/middleware/_video.py#L86-L122","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install the extra: `uv add 'deepagents[video]'` (or `pip install 'deepagents[video]'`).","Install PyAV directly if the extra is unavailable: `pip install av`.","Ensure the deployment image includes the video extra.","Catch VideoExtractionError and return the install hint to the user/agent."],"exampleFix":"// before\npip install deepagents\n// after\npip install \"deepagents[video]\"","handlingStrategy":"fallback","validationCode":"def av_available() -> bool:\n    try:\n        import av  # noqa: F401\n        return True\n    except ImportError:\n        return False","typeGuard":"def can_read_video(path: str) -> bool:\n    return path.lower().endswith((\".mp4\", \".mov\", \".webm\", \".mkv\")) and av_available()","tryCatchPattern":"try:\n    blocks = read_video(path)\nexcept VideoExtractionError as exc:\n    if \"deepagents[video]\" in str(exc):\n        return {\"error\": \"Video support not installed. Run: pip install 'deepagents[video]'\"}\n    raise","preventionTips":["Install with the video extra in all environments that may process media: pip install 'deepagents[video]'.","Include the extra in Dockerfiles and CI images.","Feature-detect `import av` at startup and disable video tools if missing.","Pin av alongside deepagents so codec support stays consistent."],"tags":["optional-dependency","video","import-error"],"backgroundTag":"missing-optional-dependency","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}