sgl-project/sglang · error · ValueError

conditions[{index}].frame_index is required

Error message

conditions[{index}].frame_index is required

What it means

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].

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/resolved_plan.py:335

        auto_aspect_ratio=profile.auto_aspect_ratio,
        auto_geometry_source=profile.auto_geometry_source,
    )

    materials: list[MiniMaxH3MaterialPlanItem] = []
    visual_encode: list[int] = []
    audio_encode: list[int] = []
    keyframe_semantic_indices: list[int] = []
    keyframe_pixel_indices: list[int] = []
    seen_keyframe_pixel_indices: dict[int, int] = {}
    for index, cond in enumerate(canonical["conditions"]):
        rule = profile.rule_for(
            role=str(cond["role"]), condition_type=str(cond["type"])
        )
        frame_index = cond.get("frame_index")
        resolved_frame_index = None
        if rule.requires_frame_index:
            if frame_index is None:
                raise ValueError(f"conditions[{index}].frame_index is required")
            semantic_frame_index = int(frame_index)
            frame_count = int(shape["frame_count"])
            if semantic_frame_index == -1:
                resolved_frame_index = frame_count - 1
            elif 0 <= semantic_frame_index < frame_count:
                resolved_frame_index = semantic_frame_index
            else:
                raise ValueError(
                    f"conditions[{index}].frame_index must be -1 or in "
                    f"[0, {frame_count}) after 17n+5 frame alignment, got "
                    f"{semantic_frame_index}"
                )
            previous = seen_keyframe_pixel_indices.get(resolved_frame_index)
            if previous is not None:
                raise ValueError(
                    f"conditions[{index}].frame_index resolves to "
                    f"{resolved_frame_index}, already bound by "
                    f"conditions[{previous}]"

View on GitHub (pinned to 0132848349)

Solutions

1. Set an explicit integer frame_index (0 or -1) on the failing condition
2. If the condition genuinely has no anchor, reclassify it to a condition type whose rule does not require frame_index

Example fix

# before
{"role":"first","type":"image"}
# after
{"role":"first","type":"image","frame_index": 0}

for i, c in enumerate(conditions):
    if rule_requires_frame_index(c):
        assert c.get("frame_index") is not None, i

def has_frame_indices(conds) -> bool:
    return all(c.get("frame_index") is not None for c in conds if is_keyframe(c))

When it happens

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

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

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

• {path}.duration_seconds is required
• {path} requires at least one entry for task {profile.task!r}
• {cpath}.frame_index requires a resolved target duration
• {cpath}.frame_index must be -1 or in [0, {aligned_frame_coun
• canonical request missing {key!r}

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