sgl-project/sglang · error · ValueError

{cpath}.frame_index must be -1 or in [0, {aligned_frame_coun

Error message

{cpath}.frame_index must be -1 or in [0, {aligned_frame_count}) after 17n+5 frame alignment, got {frame_index}

What it means

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.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/request_validation.py:220

        try:
            rule = profile.rule_for(role=role, condition_type=cond_type)
        except ValueError as exc:
            raise ValueError(f"{cpath}: {exc}") from exc
        uri = _require_str(cond.get("uri"), f"{cpath}.uri")

        entry: dict[str, Any] = {"type": cond_type, "uri": uri, "role": role}
        if rule.requires_frame_index:
            frame_index = _require_int(cond.get("frame_index"), f"{cpath}.frame_index")
            if aligned_frame_count is None:
                raise ValueError(
                    f"{cpath}.frame_index requires a resolved target duration"
                )
            if frame_index == -1:
                resolved = aligned_frame_count - 1
            elif 0 <= frame_index < aligned_frame_count:
                resolved = frame_index
            else:
                raise ValueError(
                    f"{cpath}.frame_index must be -1 or in "
                    f"[0, {aligned_frame_count}) after 17n+5 frame alignment, "
                    f"got {frame_index}"
                )
            if resolved in seen_frame_indices:
                raise ValueError(
                    f"{cpath}.frame_index resolves to {resolved}, already "
                    f"bound by conditions[{seen_frame_indices[resolved]}]"
                )
            seen_frame_indices[resolved] = index
            # Preserve the request-level semantic index.  In particular, -1 is
            # the canonical last-frame sentinel; the resolved pixel frame is
            # carried separately by MiniMaxH3ResolvedPlan.
            entry["frame_index"] = frame_index
        elif cond.get("frame_index") is not None:
            raise ValueError(f"{cpath}.frame_index is not allowed for role={role!r}")
        start_time_seconds = _optional_nonnegative_finite_float(
            cond.get("start_time_seconds"), f"{cpath}.start_time_seconds"

View on GitHub (pinned to 0132848349)

Solutions

  1. Use -1 for the last frame instead of a hard-coded end index
  2. Compute the cap via minimax_h3_align_frame_count(duration_seconds) and clamp indices into [0, cap-1]
  3. Verify you're indexing aligned frames, not raw fps-based frames

Example fix

// before
{"frame_index": last_frame_guess}
// after
{"frame_index": -1}  # canonical last-frame sentinel
Defensive patterns

Strategy: validation

Validate before calling

cap = minimax_h3_align_frame_count(duration) if duration else None
for c in conditions:
    fi = c.get('frame_index')
    if fi is not None and fi != -1 and not (0 <= fi < cap):
        c['frame_index'] = -1 if fi >= cap else 0  # or clamp

Prevention

When it happens

Trigger: 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).

Common situations: 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).

Related errors

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