sgl-project/sglang · error · ValueError

reference video has no frames: {video_path}

Error message

reference video has no frames: {video_path}

What it means

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.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/reference_encoding.py:429

        "0:v:0",
        "-an",
        "-vf",
        filters,
        "-frames:v",
        str(target_frame_count),
        "-f",
        "rawvideo",
        "-pix_fmt",
        "rgb24",
    ]
    frame_bytes = target_width * target_height * 3
    if share_across_replicas:
        payload, payload_size = _decode_reference_video_shared(command)
    else:
        payload, payload_size = _decode_reference_video_local(command)

    if payload_size <= 0:
        raise ValueError(f"reference video has no frames: {video_path}")
    if payload_size % frame_bytes:
        raise ValueError(
            "ffmpeg returned a partial reference-video frame: "
            f"{payload_size} bytes for {target_width}x{target_height} RGB24"
        )
    frame_count = payload_size // frame_bytes
    return np.frombuffer(payload, dtype=np.uint8).reshape(
        frame_count, target_height, target_width, 3
    )


def _decode_reference_video_local(command: list[str]) -> tuple[Any, int]:
    """Write one worker's RGB stream without a large stdout aggregation."""

    # Linux workers can let ffmpeg write the exact RGB24 stream into an
    # anonymous file descriptor. Mapping that output avoids communicate()'s
    # chunk list and final bytes join for a several-hundred-MiB reference.
    output_fd = -1

View on GitHub (pinned to 0132848349)

Solutions

1. Validate the video with ffprobe (has video stream, nonzero frame count, readable codec) before the pipeline
2. Re-encode the source to a standard H.264 MP4
3. If using shared decode, check /proc fd limits or the fallback path isn't silently swallowing the real ffmpeg error

Example fix

// before
submit(video_path)  # corrupt file -> ValueError

// after
if not probe_has_frames(video_path):
    raise HTTPError(400, "video has no decodable frames")
submit(video_path)

def video_has_frames(path) -> bool:
    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)
    try:
        return int(r.stdout) > 0
    except ValueError:
        return False

try:
    minimax_h3_decode_reference_video_frames(...)
except ValueError as e:
    if 'no frames' in str(e):
        return bad_request("video has no decodable frames")
    raise

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• MiniMax H3 requires ffmpeg and ffprobe for media processing
• MiniMax H3 media container format is not allowed
• MiniMax H3 video material has no usable frame rate
• hybrid ref2va layout only supports first/last keyframe ancho
• reference audio is empty: {audio_path}

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/6a49e06572db7380. Report an issue: GitHub.