sgl-project/sglang · error · ValueError

{profile.task} ResolvedPlan requires one or two ordered imag

Error message

{profile.task} ResolvedPlan requires one or two ordered image/keyframe conditions with frame_index [0], [-1], or [0, -1], got {signatures!r}

What it means

For keyframe-conditioned MiniMax H3 tasks the ResolvedPlan requires the ordered condition list to be one or two ('image','keyframe',...) entries whose frame_index signature tuple is one of MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES: (0,), (-1,), or (0, -1). Any other ordering, count, condition type, or frame signature raises this ValueError.

Source

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

        signatures = (
            [
                (
                    condition.get("type"),
                    condition.get("role"),
                    condition.get("frame_index"),
                )
                for condition in keyframe_conditions
            ]
            if all(isinstance(condition, Mapping) for condition in keyframe_conditions)
            else []
        )
        frame_signature = tuple(signature[2] for signature in signatures)
        if (
            not signatures
            or any(signature[:2] != ("image", "keyframe") for signature in signatures)
            or frame_signature not in MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES
        ):
            raise ValueError(
                f"{profile.task} ResolvedPlan requires one or two ordered "
                "image/keyframe "
                "conditions with frame_index [0], [-1], or [0, -1], got "
                f"{signatures!r}"
            )
    shape = _resolve_shape(
        canonical["target"],
        geometry_source=profile.geometry_source,
        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] = {}

View on GitHub (pinned to 0132848349)

Solutions

  1. Restructure conditions to exactly one or two ordered image keyframe conditions with frame_index 0 and/or -1
  2. Remove extra/unsupported conditions from the front of the list
  3. Check MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES in the package to confirm the allowed tuples for your version

Example fix

# before
conditions = [{"role":"first","type":"image","frame_index": 1}]
# after
conditions = [{"role":"first","type":"image","frame_index": 0}]
Defensive patterns

Strategy: validation

Validate before calling

sigs = [c.get("frame_index") for c in conditions[:2] if c.get("type")=="keyframe"]
assert tuple(sigs) in {(0,),(-1,),(0,-1)}

Type guard

def valid_keyframe_sig(conds) -> bool:
    sig = tuple(c.get("frame_index") for c in conds
                if c.get("type") == "image")
    return sig in MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES

Prevention

When it happens

Trigger: Passing zero keyframe conditions, a non-'image'/non-'keyframe' condition type among the first two conditions, or frame_index values like 1, -2, or (0, 1) that are not in the allowed signature set.

Common situations: Assuming arbitrary frame positions (e.g. mid-video frame 5) are allowed as anchors; reordering conditions so the first-frame condition comes after the last-frame one; adding a text condition in the first two slots.

Related errors

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