{"record":{"id":"6a49e06572db7380","repo":"sgl-project/sglang","slug":"reference-video-has-no-frames-video-path","errorCode":null,"errorMessage":"reference video has no frames: {video_path}","messagePattern":"reference video has no frames: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/reference_encoding.py","lineNumber":429,"sourceCode":"        \"0:v:0\",\n        \"-an\",\n        \"-vf\",\n        filters,\n        \"-frames:v\",\n        str(target_frame_count),\n        \"-f\",\n        \"rawvideo\",\n        \"-pix_fmt\",\n        \"rgb24\",\n    ]\n    frame_bytes = target_width * target_height * 3\n    if share_across_replicas:\n        payload, payload_size = _decode_reference_video_shared(command)\n    else:\n        payload, payload_size = _decode_reference_video_local(command)\n\n    if payload_size <= 0:\n        raise ValueError(f\"reference video has no frames: {video_path}\")\n    if payload_size % frame_bytes:\n        raise ValueError(\n            \"ffmpeg returned a partial reference-video frame: \"\n            f\"{payload_size} bytes for {target_width}x{target_height} RGB24\"\n        )\n    frame_count = payload_size // frame_bytes\n    return np.frombuffer(payload, dtype=np.uint8).reshape(\n        frame_count, target_height, target_width, 3\n    )\n\n\ndef _decode_reference_video_local(command: list[str]) -> tuple[Any, int]:\n    \"\"\"Write one worker's RGB stream without a large stdout aggregation.\"\"\"\n\n    # Linux workers can let ffmpeg write the exact RGB24 stream into an\n    # anonymous file descriptor. Mapping that output avoids communicate()'s\n    # chunk list and final bytes join for a several-hundred-MiB reference.\n    output_fd = -1","sourceCodeStart":411,"sourceCodeEnd":447,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/reference_encoding.py#L411-L447","documentation":"Video frame decoding (shared or local) returned zero bytes, meaning the ffmpeg pipe yielded no frames for the reference video. The check runs in minimax_h3_decode_reference_video_frames after either decode path.","triggerScenarios":"A video path that is empty/corrupt, an ffmpeg seek past the end, or a shared decode that failed and returned an empty payload (the fallback path in the tests also exercises this).","commonSituations":"Zero-byte or truncated uploads, unsupported codecs where ffmpeg errors before writing frames, or wrong dimensions in the decode command causing ffmpeg to output nothing.","solutions":["Validate the video with ffprobe (has video stream, nonzero frame count, readable codec) before the pipeline","Re-encode the source to a standard H.264 MP4","If using shared decode, check /proc fd limits or the fallback path isn't silently swallowing the real ffmpeg error"],"exampleFix":"// before\nsubmit(video_path)  # corrupt file -> ValueError\n\n// after\nif not probe_has_frames(video_path):\n    raise HTTPError(400, \"video has no decodable frames\")\nsubmit(video_path)","handlingStrategy":"validation","validationCode":"def video_has_frames(path) -> bool:\n    r = subprocess.run([\"ffprobe\",\"-v\",\"error\",\"-count_frames\",\"-select_streams\",\"v:0\",\"-show_entries\",\"stream=nb_read_frames\",\"-of\",\"csv=p=0\",path], capture_output=True)\n    try:\n        return int(r.stdout) > 0\n    except ValueError:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    minimax_h3_decode_reference_video_frames(...)\nexcept ValueError as e:\n    if 'no frames' in str(e):\n        return bad_request(\"video has no decodable frames\")\n    raise","preventionTips":["Reject zero-byte and truncated video uploads","Re-encode exotic codecs to H.264 before submission"],"tags":["minimax-h3","video","empty-media","ffmpeg"],"backgroundTag":"empty-video-frames","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}