sgl-project/sglang · error · ValueError

keyframe payload frame_count must be greater than one

Error message

keyframe payload frame_count must be greater than one

What it means

The keyframe payload's frame_count must be > 1, because at least two distinct pixel frames are needed for first/last-frame anchoring to be meaningful.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/denoising.py:108

    if keyframe is None:
        if task == "fl2va":
            raise ValueError("fl2va denoising requires encoded keyframe condition rows")
        return
    if not isinstance(keyframe, Mapping):
        raise ValueError("encoded keyframe condition rows must be a mapping")

    semantic_indices = tuple(keyframe.get("semantic_frame_indices") or ())
    if semantic_indices not in MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES:
        raise ValueError(
            "keyframe denoising requires semantic_frame_indices in "
            f"{MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES!r}, "
            f"got {semantic_indices!r}"
        )
    frame_count = keyframe.get("frame_count")
    if isinstance(frame_count, bool) or not isinstance(frame_count, int):
        raise ValueError("keyframe payload requires an integer frame_count")
    if frame_count <= 1:
        raise ValueError("keyframe payload frame_count must be greater than one")
    pixel_indices = keyframe.get("pixel_frame_indices")
    expected_pixel_indices = [
        frame_count - 1 if index == -1 else index for index in semantic_indices
    ]
    if pixel_indices != expected_pixel_indices:
        raise ValueError(
            "keyframe denoising requires pixel_frame_indices resolved from the "
            "semantic anchors, "
            f"got {pixel_indices!r} for frame_count={frame_count}"
        )

    entries = keyframe.get("keyframes")
    if (
        not isinstance(entries, list)
        or len(entries) != len(semantic_indices)
        or any(not isinstance(entry, Mapping) for entry in entries)
    ):
        raise ValueError(

View on GitHub (pinned to 0132848349)

Solutions

1. Increase requested duration/resolution so the aligned frame count exceeds 1
2. Fix the producer's frame_count computation
3. For genuinely one-frame conditioning, don't send a keyframe payload (use a non-keyframe task)

Example fix

# before
request.duration = 0.04  # aligns to 1 frame
# after
request.duration = 1.0  # aligns to >1 frames

assert keyframe["frame_count"] > 1

def valid_frame_count(v) -> bool:
    return (not isinstance(v, bool)) and isinstance(v, int) and v > 1

When it happens

Trigger: frame_count == 0, 1, or negative in the encoded keyframe payload — typically a one-frame video after 17n+5 alignment, or a zero/negative count from a buggy producer.

Common situations: Very short duration requests resolving to a single frame; upstream off-by-one computing frame_count; test fixtures with degenerate clip lengths.

Related errors

• keyframe payload requires an integer frame_count
• hybrid ref2va layout only supports first/last keyframe ancho
• {profile.task} ResolvedPlan requires one or two ordered imag
• keyframe condition rows require plan.task='fl2va' or 'ref2va
• fl2va denoising requires encoded keyframe condition rows

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