sgl-project/sglang · error · ValueError

MiniMax H3 text encoding requires an ordered keyframe signat

Error message

MiniMax H3 text encoding requires an ordered keyframe signature in {MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES!r}, got {frame_indices!r}

What it means

For fl2va/ref2va tasks, the ordered tuple of frame_index values of 'image.target_canvas' materials must be one of the supported signatures in MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES (first-frame and first+last-frame layouts). Any other ordering or set of keyframes is rejected before encoding.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/text_encoding.py:263

        """Encode the positive Qwen3VL presentation into layer-50 states.

        MiniMax H3 only supports the CFG-distilled model path, so every task
        emits exactly one positive embedding payload. ComponentManager owns
        residency/offload, while every folded-TP rank enters the encoder
        collectives and receives the same replicated hidden states.
        """
        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.presentation import (
            minimax_h3_text_only_ids,
        )

        prompt = plan.prompt
        keyframes = [
            m for m in plan.materials if m.material_chain == "image.target_canvas"
        ]
        if plan.task in {"fl2va", "ref2va"} and keyframes:
            frame_indices = tuple(material.frame_index for material in keyframes)
            if frame_indices not in MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES:
                raise ValueError(
                    "MiniMax H3 text encoding requires an ordered keyframe signature "
                    f"in {MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES!r}, got "
                    f"{frame_indices!r}"
                )
        elif keyframes:
            raise ValueError(
                f"task {plan.task!r} cannot carry image.target_canvas materials"
            )
        if MINIMAX_H3_TEXT_EMBEDDINGS_EXTRA_KEY in batch.extra:
            return
        if self.text_encoder is None:
            raise ValueError(
                "MiniMaxH3TextEncodingStage direct encode requires a text_encoder "
                "component"
            )
        encode_ids = getattr(self.text_encoder, "encode_ids", None)
        if not callable(encode_ids):
            raise TypeError(

View on GitHub (pinned to 0132848349)

Solutions

1. Constrain keyframe materials to the supported signatures: first frame only, or first+last frame in order
2. If building plans programmatically, derive frame_index from the allowed signature constants rather than user-supplied indices
3. Regenerate the plan through the canonical request builder

idx = tuple(m.frame_index for m in plan.materials if m.material_chain == "image.target_canvas")
assert plan.task not in {"fl2va", "ref2va"} or not idx or idx in MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES, idx

def valid_keyframe_signature(plan) -> bool:
    if plan.task not in {"fl2va", "ref2va"}:
        return True
    idx = tuple(m.frame_index for m in plan.materials if m.material_chain == "image.target_canvas")
    return not idx or idx in MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES

When it happens

Trigger: _encode_from_plan sees plan.task in {'fl2va','ref2va'} with keyframe materials whose tuple of frame_index values is not in the allowed set — e.g. a mid-video frame (index 2), duplicate indices, or reversed ordering.

Common situations: Clients constructing plans by hand with arbitrary frame indices, upstream request parsing that maps user keyframes to wrong frame_index values, or format changes to keyframe signature constants.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• conditions for task {task!r} must include one or two ordered
• fl2va Qwen preparation requires one or two ordered images wi
• keyframe visual preparation requires one or two ordered imag
• keyframe resolved_frame_index values disagree with semantic
• cached keyframe preparation disagrees with the resolved plan

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