{"record":{"id":"8703500c5a1715a0","repo":"langchain-ai/deepagents","slug":"failed-to-decode-video-frames-exc","errorCode":null,"errorMessage":"Failed to decode video frames: {exc}","messagePattern":"Failed to decode video frames: (.+?)","errorType":"exception","errorClass":"VideoExtractionError","httpStatus":null,"severity":"error","filePath":"libs/deepagents/deepagents/middleware/_video.py","lineNumber":191,"sourceCode":"                # at a non-zero timeline (e.g. trimmed clips).\n                start_pts = _stream_start_pts(video_stream) + int(offset_seconds / time_base)\n                container.seek(start_pts, any_frame=False, backward=True, stream=video_stream)\n\n            blocks = list(\n                _sample_frames_in_window(\n                    container.decode(video_stream),\n                    offset_seconds=offset_seconds,\n                    duration_seconds=float(duration),\n                    sampling_rate=rate,\n                    time_base=time_base,\n                    stream_start_seconds=stream_start_seconds,\n                    deadline_seconds=time.monotonic() + MAX_VIDEO_DECODE_SECONDS,\n                    decode_error_types=backend_error_types,\n                )\n            )\n        except backend_error_types as exc:\n            msg = f\"Failed to decode video frames: {exc}\"\n            raise VideoExtractionError(msg) from exc\n    finally:\n        container.close()\n\n    if not blocks:\n        end_seconds = offset_seconds + duration\n        msg = f\"No frames decoded for window [{offset_seconds:.3f}s, {end_seconds:.3f}s)\"\n        raise VideoExtractionError(msg)\n    return blocks\n\n\ndef _validate_video_window(*, offset_seconds: float, duration_seconds: float, sampling_rate: float) -> None:\n    \"\"\"Validate the requested sampling window before opening the video.\"\"\"\n    if offset_seconds < 0:\n        msg = f\"offset_seconds must be >= 0, got {offset_seconds!r}\"\n        raise ValueError(msg)\n    if sampling_rate <= 0:\n        msg = f\"sampling_rate must be > 0, got {sampling_rate!r}\"\n        raise ValueError(msg)","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/deepagents/deepagents/middleware/_video.py#L173-L209","documentation":"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.","triggerScenarios":"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.","commonSituations":"Missing FFmpeg codecs for HEVC/AV1/ProRes in the environment; corrupted or partially downloaded media; encrypted commercial streams.","solutions":["Re-encode the video to H.264 with ffmpeg: `ffmpeg -i in.mov -c:v libx264 -c:a aac out.mp4`.","Upgrade av/PyAV (and its bundled FFmpeg): `pip install -U av`.","Check whether the stream is encrypted/DRM-protected; obtain a decodable copy.","Catch VideoExtractionError, log the underlying decode error, and degrade gracefully."],"exampleFix":"// before\nframes = extract_video_frames(hevc_bytes)  # codec not supported\n// after\nsubprocess.run([\"ffmpeg\", \"-y\", \"-i\", \"in.mp4\", \"-c:v\", \"libx264\", \"out.mp4\"])\nframes = extract_video_frames(open(\"out.mp4\", \"rb\").read())","handlingStrategy":"try-catch","validationCode":"def probe_decodable(path: str) -> bool:\n    import subprocess\n    r = subprocess.run([\"ffprobe\", \"-v\", \"error\", \"-select_streams\", \"v\", path], capture_output=True)\n    return r.returncode == 0 and r.stdout != b\"\"","typeGuard":null,"tryCatchPattern":"try:\n    frames = extract_video_frames(content, offset_seconds=0, duration_seconds=10)\nexcept VideoExtractionError as exc:\n    if str(exc).startswith(\"Failed to decode video frames\"):\n        transcoded = transcode_to_h264(content)\n        frames = extract_video_frames(transcoded, offset_seconds=0, duration_seconds=10)\n    else:\n        raise","preventionTips":["Install a PyAV build with broad codec support (or the deepagents[video] extra with system FFmpeg).","Transcode HEVC/AV1/ProRes sources to H.264 before agent processing.","Reject encrypted/DRM streams at ingest.","Keep av upgraded to pick up new codec support."],"tags":["video","decoding","pyav","codec"],"backgroundTag":"video-decode-failed","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}