{"record":{"id":"fad65cbbd4ff724d","repo":"sgl-project/sglang","slug":"keyframe-payload-frame-count-must-be-greater-than","errorCode":null,"errorMessage":"keyframe payload frame_count must be greater than one","messagePattern":"keyframe payload frame_count must be greater than one","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/denoising.py","lineNumber":108,"sourceCode":"    if keyframe is None:\n        if task == \"fl2va\":\n            raise ValueError(\"fl2va denoising requires encoded keyframe condition rows\")\n        return\n    if not isinstance(keyframe, Mapping):\n        raise ValueError(\"encoded keyframe condition rows must be a mapping\")\n\n    semantic_indices = tuple(keyframe.get(\"semantic_frame_indices\") or ())\n    if semantic_indices not in MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES:\n        raise ValueError(\n            \"keyframe denoising requires semantic_frame_indices in \"\n            f\"{MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES!r}, \"\n            f\"got {semantic_indices!r}\"\n        )\n    frame_count = keyframe.get(\"frame_count\")\n    if isinstance(frame_count, bool) or not isinstance(frame_count, int):\n        raise ValueError(\"keyframe payload requires an integer frame_count\")\n    if frame_count <= 1:\n        raise ValueError(\"keyframe payload frame_count must be greater than one\")\n    pixel_indices = keyframe.get(\"pixel_frame_indices\")\n    expected_pixel_indices = [\n        frame_count - 1 if index == -1 else index for index in semantic_indices\n    ]\n    if pixel_indices != expected_pixel_indices:\n        raise ValueError(\n            \"keyframe denoising requires pixel_frame_indices resolved from the \"\n            \"semantic anchors, \"\n            f\"got {pixel_indices!r} for frame_count={frame_count}\"\n        )\n\n    entries = keyframe.get(\"keyframes\")\n    if (\n        not isinstance(entries, list)\n        or len(entries) != len(semantic_indices)\n        or any(not isinstance(entry, Mapping) for entry in entries)\n    ):\n        raise ValueError(","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/denoising.py#L90-L126","documentation":"The keyframe payload's frame_count must be > 1, because at least two distinct pixel frames are needed for first/last-frame anchoring to be meaningful.","triggerScenarios":"frame_count == 0, 1, or negative in the encoded keyframe payload — typically a one-frame video after 17n+5 alignment, or a zero/negative count from a buggy producer.","commonSituations":"Very short duration requests resolving to a single frame; upstream off-by-one computing frame_count; test fixtures with degenerate clip lengths.","solutions":["Increase requested duration/resolution so the aligned frame count exceeds 1","Fix the producer's frame_count computation","For genuinely one-frame conditioning, don't send a keyframe payload (use a non-keyframe task)"],"exampleFix":"# before\nrequest.duration = 0.04  # aligns to 1 frame\n# after\nrequest.duration = 1.0  # aligns to >1 frames","handlingStrategy":"validation","validationCode":"assert keyframe[\"frame_count\"] > 1","typeGuard":"def valid_frame_count(v) -> bool:\n    return (not isinstance(v, bool)) and isinstance(v, int) and v > 1","tryCatchPattern":null,"preventionTips":["Avoid degenerate one-frame clip requests","Sanity-check aligned frame count before attaching payload"],"tags":["minimax-h3","keyframe","frame-count","boundary"],"backgroundTag":"value-out-of-range","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}