sgl-project/sglang · error · ValueError

{cpath}.frame_index requires a resolved target duration

Error message

{cpath}.frame_index requires a resolved target duration

What it means

A condition whose rule requires frame_index was validated, but no target duration was resolved, so the frame count (via minimax_h3_align_frame_count) is unknown and frame_index cannot be bounds-checked.

Source

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

        if role not in (
            MINIMAX_H3_CONDITION_ROLE_KEYFRAME,
            MINIMAX_H3_CONDITION_ROLE_REFERENCE,
        ):
            raise ValueError(
                f"{cpath}.role must be keyframe or reference, " f"got {role!r}"
            )
        cond_type = _require_str(cond.get("type"), f"{cpath}.type")
        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

View on GitHub (pinned to 0132848349)

Solutions

1. Add target.duration_seconds so the frame count can be computed
2. Or attach the audio reference the profile uses to derive duration

Example fix

// before
{"target": {"short_edge": 768, "aspect_ratio": "auto"}, "conditions": [{..., "frame_index": 0}]}
// after
{"target": {"short_edge": 768, "aspect_ratio": "auto", "duration_seconds": 6}, "conditions": [{..., "frame_index": 0}]}

needs_fi = any(c.get('frame_index') is not None for c in conditions)
if needs_fi and 'duration_seconds' not in target and not profile.duration_from_audio_reference:
    raise ValueError('set duration_seconds before using frame_index')

When it happens

Trigger: Keyframe condition with frame_index set while target.duration_seconds is absent and the task can't derive duration from audio.

Common situations: Omitting duration on keyframe-driven requests; audio reference missing so duration derivation fails silently until this point.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• MiniMax H3 media material has no positive duration
• {path}.duration_seconds is required
• {path}.duration_seconds must be a number
• {path}.duration_seconds must be positive
• {path}.duration_seconds must be in [{MINIMAX_H3_MIN_DURATION

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