sgl-project/sglang · error · ValueError

encoded keyframe condition rows must be a mapping

Error message

encoded keyframe condition rows must be a mapping

What it means

The encoded keyframe payload attached to the batch must be a Mapping (dict-like) with keys like semantic_frame_indices, frame_count, pixel_frame_indices, keyframes. Any other type raises ValueError.

Source

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

    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 = [
        frame_count - 1 if index == -1 else index for index in semantic_indices
    ]
    if pixel_indices != expected_pixel_indices:

View on GitHub (pinned to 0132848349)

Solutions

1. Convert the payload to a dict with the documented keys
2. Update custom stage code to emit the Mapping-based keyframe schema

Example fix

# before
batch.keyframe = [kf0, kf1]  # legacy list
# after
batch.keyframe = {"semantic_frame_indices": (0, -1), "frame_count": n, "pixel_frame_indices": [0, n-1], "keyframes": [...]}

assert isinstance(keyframe, Mapping)

from collections.abc import Mapping
def is_mapping_payload(k) -> bool:
    return isinstance(k, Mapping)

When it happens

Trigger: Attaching a list of tensors, a tuple, or a custom non-Mapping object as the keyframe payload.

Common situations: Custom stages writing the keyframe extra in an older list-based format after a format change to the mapping schema.

Related errors

• keyframe payload requires an integer frame_count
• keyframe denoising requires one encoded keyframe per semanti
• subblock_sparse_query_block_mask must be a tensor
• strict fl2va packed layout requires integer keyframe_frame_i
• hybrid ref2va layout only supports first/last keyframe ancho

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