sgl-project/sglang · error · ValueError

strict fl2va packed layout requires keyframe_frame_indices

Error message

strict fl2va packed layout requires keyframe_frame_indices

What it means

include_keyframe_cond=True but keyframe_frame_indices was None. The strict fl2va packed layout cannot be built without explicit keyframe frame positions.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/packed_sequence.py:50

_FRAME_PER_TOKEN = (1, 4, 4, 4, 4)
_FRAME_RESCALE = 5.0 / 3.0
_PATCH_H = 2
_PATCH_W = 2


def _keyframe_cond_frame_indices(
    *,
    include_keyframe_cond: bool,
    keyframe_frame_indices: list[int] | tuple[int, ...] | None,
) -> list[int]:
    if not include_keyframe_cond:
        if keyframe_frame_indices is not None:
            raise ValueError(
                "keyframe_frame_indices must be omitted when keyframe cond is not included"
            )
        return []
    if keyframe_frame_indices is None:
        raise ValueError("strict fl2va packed layout requires keyframe_frame_indices")
    if any(
        isinstance(value, bool) or not isinstance(value, int)
        for value in keyframe_frame_indices
    ):
        raise ValueError(
            "strict fl2va packed layout requires integer keyframe_frame_indices"
        )
    out = list(keyframe_frame_indices)
    if tuple(out) not in MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES:
        raise ValueError(
            "strict fl2va packed layout requires keyframe_frame_indices in "
            f"{MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES!r}, got {out!r}"
        )
    return out


def _resolve_keyframe_frame_indices(
    frame_indices: Sequence[int],

View on GitHub (pinned to 0132848349)

Solutions

1. Provide keyframe_frame_indices matching the enabled keyframes (e.g. [0] or [0, N-1])
2. Or disable include_keyframe_cond if conditioning is not needed
3. Validate both options together at config load time

Example fix

# before
seq = minimax_h3_packed_sequence(..., include_keyframe_cond=True, keyframe_frame_indices=None)
# after
seq = minimax_h3_packed_sequence(..., include_keyframe_cond=True, keyframe_frame_indices=[0])

if include_keyframe_cond:
    assert keyframe_frame_indices is not None, 'indices required'

except ValueError as e: supply indices or disable keyframe cond

When it happens

Trigger: Calling minimax_h3_packed_sequence(..., include_keyframe_cond=True) without providing keyframe_frame_indices.

Common situations: Enabling keyframe conditioning in config while forgetting to set the frame indices; default None field passed through.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• x must be [1, S, C], got {list(x.shape)}
• token_tags must cover the full packed sequence ({seq_len}),
• inverse_indices must be [{seq_len}], got {list(inverse_indic
• keyframe_frame_indices must be omitted when keyframe cond is
• task is required for MiniMax H3; supported tasks: fl2va, ref

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