{"record":{"id":"0aa05a55db41bb07","repo":"sgl-project/sglang","slug":"keyframe-visual-preparation-requires-one-or-two-or","errorCode":null,"errorMessage":"keyframe visual preparation requires one or two ordered images with a supported semantic_frame_indices signature","messagePattern":"keyframe visual preparation requires one or two ordered images with a supported semantic_frame_indices signature","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/visual_encoding.py","lineNumber":234,"sourceCode":"\n    def _encode_target_keyframes(self, batch: Req, plan) -> None:\n        if MINIMAX_H3_KEYFRAME_COND_ROWS_EXTRA_KEY in batch.extra:\n            return\n        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.canvas import (\n            minimax_h3_prepared_keyframes,\n        )\n        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.keyframe_encoding import (\n            minimax_h3_encode_keyframe_cond_rows,\n        )\n\n        # Parallel tiling gives each replicated rank complete tiles, then gathers\n        # them before the seeded posterior sample.\n        prepared = minimax_h3_prepared_keyframes(batch, plan)\n        prepared_indices = tuple(prepared.get(\"semantic_frame_indices\") or ())\n        if prepared_indices not in MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES or len(\n            prepared.get(\"images\") or ()\n        ) != len(prepared_indices):\n            raise ValueError(\n                \"keyframe visual preparation requires one or two ordered images \"\n                \"with a supported semantic_frame_indices signature\"\n            )\n        encoded = []\n        rows_list = []\n        for item in prepared[\"images\"]:\n            image = item[\"image\"]\n            width, height = item[\"canvas_width\"], item[\"canvas_height\"]\n            # The encode sampling seed is pinned at 42 (the VAE sample\n            # seed is part of the contract), independent of the request seed.\n            rows = minimax_h3_encode_keyframe_cond_rows(\n                self.video_vae,\n                image,\n                self.vae_arch_config,\n            )\n            encoded.append(\n                {\n                    \"rows\": rows,","sourceCodeStart":216,"sourceCodeEnd":252,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/visual_encoding.py#L216-L252","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure exactly 1 or 2 ordered keyframe images are provided for fl2va tasks","Verify semantic_frame_indices is populated and matches one of MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES","Check len(images) == len(semantic_frame_indices) in your request before submitting","Inspect what minimax_h3_prepared_keyframes returns to see where indices are lost"],"exampleFix":"// before\nrequest[\"images\"] = [img1, img2, img3]\n\n// after\nrequest[\"images\"] = [img1, img2]  # first & last frame only\nrequest[\"semantic_frame_indices\"] = [0, 1]","handlingStrategy":"type-guard","validationCode":"idx = tuple(payload.get(\"semantic_frame_indices\") or ())\nimgs = payload.get(\"images\") or ()\nassert 1 <= len(imgs) <= 2 and len(imgs) == len(idx), \"need 1-2 images with matching indices\"","typeGuard":"def is_valid_keyframe_payload(p: dict) -> bool:\n    idx = tuple(p.get(\"semantic_frame_indices\") or ())\n    imgs = p.get(\"images\") or ()\n    return bool(idx) and len(imgs) == len(idx) and len(imgs) <= 2","tryCatchPattern":"catch ValueError from the encode call, re-raise with the prepared payload dumped for debugging","preventionTips":["Validate image count and indices together client-side","Never send more than first/last frame images for fl2va"],"tags":["minimax-h3","keyframes","fl2va","payload-validation"],"backgroundTag":"schema-validation-failed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}