{"record":{"id":"d6c8e86c8f9e2e49","repo":"sgl-project/sglang","slug":"conditions-index-frame-index-is-required","errorCode":null,"errorMessage":"conditions[{index}].frame_index is required","messagePattern":"conditions\\[(.+?)\\]\\.frame_index is required","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/resolved_plan.py","lineNumber":335,"sourceCode":"        auto_aspect_ratio=profile.auto_aspect_ratio,\n        auto_geometry_source=profile.auto_geometry_source,\n    )\n\n    materials: list[MiniMaxH3MaterialPlanItem] = []\n    visual_encode: list[int] = []\n    audio_encode: list[int] = []\n    keyframe_semantic_indices: list[int] = []\n    keyframe_pixel_indices: list[int] = []\n    seen_keyframe_pixel_indices: dict[int, int] = {}\n    for index, cond in enumerate(canonical[\"conditions\"]):\n        rule = profile.rule_for(\n            role=str(cond[\"role\"]), condition_type=str(cond[\"type\"])\n        )\n        frame_index = cond.get(\"frame_index\")\n        resolved_frame_index = None\n        if rule.requires_frame_index:\n            if frame_index is None:\n                raise ValueError(f\"conditions[{index}].frame_index is required\")\n            semantic_frame_index = int(frame_index)\n            frame_count = int(shape[\"frame_count\"])\n            if semantic_frame_index == -1:\n                resolved_frame_index = frame_count - 1\n            elif 0 <= semantic_frame_index < frame_count:\n                resolved_frame_index = semantic_frame_index\n            else:\n                raise ValueError(\n                    f\"conditions[{index}].frame_index must be -1 or in \"\n                    f\"[0, {frame_count}) after 17n+5 frame alignment, got \"\n                    f\"{semantic_frame_index}\"\n                )\n            previous = seen_keyframe_pixel_indices.get(resolved_frame_index)\n            if previous is not None:\n                raise ValueError(\n                    f\"conditions[{index}].frame_index resolves to \"\n                    f\"{resolved_frame_index}, already bound by \"\n                    f\"conditions[{previous}]\"","sourceCodeStart":317,"sourceCodeEnd":353,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/resolved_plan.py#L317-L353","documentation":"When the task profile's rule sets requires_frame_index, each keyframe condition must carry a non-None 'frame_index'. This ValueError names the offending conditions[index].","triggerScenarios":"A condition whose dict has no 'frame_index' key or sets it to None while the task rule requires it (e.g. fl2va first/last-frame anchoring).","commonSituations":"Copying a non-keyframe condition template; JSON payloads where frame_index was stripped because it was null; switching a task from ref2va (optional) to fl2va (required) without updating conditions.","solutions":["Set an explicit integer frame_index (0 or -1) on the failing condition","If the condition genuinely has no anchor, reclassify it to a condition type whose rule does not require frame_index"],"exampleFix":"# before\n{\"role\":\"first\",\"type\":\"image\"}\n# after\n{\"role\":\"first\",\"type\":\"image\",\"frame_index\": 0}","handlingStrategy":"validation","validationCode":"for i, c in enumerate(conditions):\n    if rule_requires_frame_index(c):\n        assert c.get(\"frame_index\") is not None, i","typeGuard":"def has_frame_indices(conds) -> bool:\n    return all(c.get(\"frame_index\") is not None for c in conds if is_keyframe(c))","tryCatchPattern":null,"preventionTips":["Always set explicit frame_index on keyframe conditions","Don't emit null frame_index keys in JSON"],"tags":["minimax-h3","frame-index","required-field"],"backgroundTag":"missing-required-field","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}