{"record":{"id":"cfe06771e3461a27","repo":"sgl-project/sglang","slug":"cpath-frame-index-must-be-1-or-in-0-aligned","errorCode":null,"errorMessage":"{cpath}.frame_index must be -1 or in [0, {aligned_frame_count}) after 17n+5 frame alignment, got {frame_index}","messagePattern":"(.+?)\\.frame_index must be -1 or in \\[0, (.+?)\\) after 17n\\+5 frame alignment, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/request_validation.py","lineNumber":220,"sourceCode":"        try:\n            rule = profile.rule_for(role=role, condition_type=cond_type)\n        except ValueError as exc:\n            raise ValueError(f\"{cpath}: {exc}\") from exc\n        uri = _require_str(cond.get(\"uri\"), f\"{cpath}.uri\")\n\n        entry: dict[str, Any] = {\"type\": cond_type, \"uri\": uri, \"role\": role}\n        if rule.requires_frame_index:\n            frame_index = _require_int(cond.get(\"frame_index\"), f\"{cpath}.frame_index\")\n            if aligned_frame_count is None:\n                raise ValueError(\n                    f\"{cpath}.frame_index requires a resolved target duration\"\n                )\n            if frame_index == -1:\n                resolved = aligned_frame_count - 1\n            elif 0 <= frame_index < aligned_frame_count:\n                resolved = frame_index\n            else:\n                raise ValueError(\n                    f\"{cpath}.frame_index must be -1 or in \"\n                    f\"[0, {aligned_frame_count}) after 17n+5 frame alignment, \"\n                    f\"got {frame_index}\"\n                )\n            if resolved in seen_frame_indices:\n                raise ValueError(\n                    f\"{cpath}.frame_index resolves to {resolved}, already \"\n                    f\"bound by conditions[{seen_frame_indices[resolved]}]\"\n                )\n            seen_frame_indices[resolved] = index\n            # Preserve the request-level semantic index.  In particular, -1 is\n            # the canonical last-frame sentinel; the resolved pixel frame is\n            # carried separately by MiniMaxH3ResolvedPlan.\n            entry[\"frame_index\"] = frame_index\n        elif cond.get(\"frame_index\") is not None:\n            raise ValueError(f\"{cpath}.frame_index is not allowed for role={role!r}\")\n        start_time_seconds = _optional_nonnegative_finite_float(\n            cond.get(\"start_time_seconds\"), f\"{cpath}.start_time_seconds\"","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/request_validation.py#L202-L238","documentation":"frame_index is not -1 and not within [0, aligned_frame_count), where aligned_frame_count comes from the 17n+5 frame alignment of the resolved duration. -1 is the last-frame sentinel; all other indices must fit the aligned frame budget.","triggerScenarios":"frame_index=100 on a 6-second clip whose aligned frame count is much smaller; using frame counts computed without the 17n+5 alignment (e.g. duration*fps).","commonSituations":"Computing expected frame counts as duration*25 instead of the 17n+5 alignment; off-by-one using aligned_frame_count itself (use -1 or count-1 for the last frame).","solutions":["Use -1 for the last frame instead of a hard-coded end index","Compute the cap via minimax_h3_align_frame_count(duration_seconds) and clamp indices into [0, cap-1]","Verify you're indexing aligned frames, not raw fps-based frames"],"exampleFix":"// before\n{\"frame_index\": last_frame_guess}\n// after\n{\"frame_index\": -1}  # canonical last-frame sentinel","handlingStrategy":"validation","validationCode":"cap = minimax_h3_align_frame_count(duration) if duration else None\nfor c in conditions:\n    fi = c.get('frame_index')\n    if fi is not None and fi != -1 and not (0 <= fi < cap):\n        c['frame_index'] = -1 if fi >= cap else 0  # or clamp","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use -1 for the last frame","Compute caps with minimax_h3_align_frame_count, not duration*fps"],"tags":["minimax-h3","frame-index","bounds-check","frame-alignment"],"backgroundTag":"index-out-of-range","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}