sgl-project/sglang · error · ValueError

keyframe visual preparation requires one or two ordered imag

Error message

keyframe visual preparation requires one or two ordered images with a supported semantic_frame_indices signature

What it means

After minimax_h3_prepared_keyframes prepares the batch, the stage requires that semantic_frame_indices match one of the MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES and that the number of images equals the number of indices. One or two ordered images with a recognized signature are the only supported keyframe layouts. A mismatch means the prepared payload is malformed for the FL2VA keyframe encoder.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/visual_encoding.py:234

    def _encode_target_keyframes(self, batch: Req, plan) -> None:
        if MINIMAX_H3_KEYFRAME_COND_ROWS_EXTRA_KEY in batch.extra:
            return
        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.canvas import (
            minimax_h3_prepared_keyframes,
        )
        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.keyframe_encoding import (
            minimax_h3_encode_keyframe_cond_rows,
        )

        # Parallel tiling gives each replicated rank complete tiles, then gathers
        # them before the seeded posterior sample.
        prepared = minimax_h3_prepared_keyframes(batch, plan)
        prepared_indices = tuple(prepared.get("semantic_frame_indices") or ())
        if prepared_indices not in MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES or len(
            prepared.get("images") or ()
        ) != len(prepared_indices):
            raise ValueError(
                "keyframe visual preparation requires one or two ordered images "
                "with a supported semantic_frame_indices signature"
            )
        encoded = []
        rows_list = []
        for item in prepared["images"]:
            image = item["image"]
            width, height = item["canvas_width"], item["canvas_height"]
            # The encode sampling seed is pinned at 42 (the VAE sample
            # seed is part of the contract), independent of the request seed.
            rows = minimax_h3_encode_keyframe_cond_rows(
                self.video_vae,
                image,
                self.vae_arch_config,
            )
            encoded.append(
                {
                    "rows": rows,

View on GitHub (pinned to 0132848349)

Solutions

  1. Ensure exactly 1 or 2 ordered keyframe images are provided for fl2va tasks
  2. Verify semantic_frame_indices is populated and matches one of MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES
  3. Check len(images) == len(semantic_frame_indices) in your request before submitting
  4. Inspect what minimax_h3_prepared_keyframes returns to see where indices are lost

Example fix

// before
request["images"] = [img1, img2, img3]

// after
request["images"] = [img1, img2]  # first & last frame only
request["semantic_frame_indices"] = [0, 1]
Defensive patterns

Strategy: type-guard

Validate before calling

idx = tuple(payload.get("semantic_frame_indices") or ())
imgs = payload.get("images") or ()
assert 1 <= len(imgs) <= 2 and len(imgs) == len(idx), "need 1-2 images with matching indices"

Type guard

def is_valid_keyframe_payload(p: dict) -> bool:
    idx = tuple(p.get("semantic_frame_indices") or ())
    imgs = p.get("images") or ()
    return bool(idx) and len(imgs) == len(idx) and len(imgs) <= 2

Try / catch

catch ValueError from the encode call, re-raise with the prepared payload dumped for debugging

Prevention

When it happens

Trigger: Calling the fl2va pipeline with zero or more than two keyframe images, images in the wrong order/structure, or a semantic_frame_indices tuple that isn't in the known signatures table. Also triggered when images is non-empty but semantic_frame_indices is missing/empty, or lengths disagree.

Common situations: Passing 3+ reference images for a first/last-frame video task; omitting semantic_frame_indices when constructing the request; a preprocessing bug in minimax_h3_prepared_keyframes that drops the indices field; schema drift after upgrading the runtime.

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

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