sgl-project/sglang · error · ValueError

fl2va denoising requires encoded keyframe condition rows

Error message

fl2va denoising requires encoded keyframe condition rows

What it means

For task 'fl2va' (first/last-frame-to-video) the denoiser requires encoded keyframe condition rows; a None keyframe payload at the DiT sink raises this ValueError.

Source

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

    )
    if audio_noise_aug is None:
        audio_noise_aug = MINIMAX_H3_AUDIO_REF_COND_TIMESTEP
    return float(imgvid_noise_aug), float(audio_noise_aug)


def _validate_keyframe_payload(plan: Any, keyframe: Any) -> None:
    """Reject stale/middle/reordered keyframe payloads at the DiT sink."""

    task = None if plan is None else str(plan.task)
    if task not in {"fl2va", "ref2va"}:
        if keyframe is not None:
            raise ValueError(
                "keyframe condition rows require plan.task='fl2va' or 'ref2va'"
            )
        return
    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 = [

View on GitHub (pinned to 0132848349)

Solutions

Verify the keyframe encoding stage ran and attached rows to the batch before denoising
If the request has no keyframes, use a task other than fl2va (e.g. t2v)
Debug stage order in the pipeline so encoded keyframes survive to the sink

Defensive patterns

Strategy: validation

Validate before calling

if plan.task == "fl2va":
    assert batch.keyframe is not None, "encoded keyframe rows missing"

Type guard

def fl2va_ready(plan, batch) -> bool:
    return plan.task != "fl2va" or batch.keyframe is not None

Prevention

Verify keyframe-encode stage ran before denoise
Use non-keyframe tasks when no keyframes exist

When it happens

Trigger: Running fl2va where the audio-encoding/keyframe stages failed to attach the encoded keyframe rows, or they were dropped between stages.

Common situations: Stage ordering bugs that skip the keyframe encoding stage; batches mutated/cleared between encode and denoise; ref2va (where keyframes are optional) request mislabeled as fl2va.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

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