sgl-project/sglang · error · ValueError

keyframe resolved_frame_index values disagree with semantic

Error message

keyframe resolved_frame_index values disagree with semantic anchors: expected {expected_pixels!r}, got {resolved_pixels!r}

What it means

During MiniMax-H3 keyframe preparation, each keyframe material carries a resolved_frame_index that must exactly match the semantic anchor indices derived from the plan (with -1 mapped to frame_count-1). This ValueError fires when any material's resolved index disagrees with the computed expectation tuple. It guards against plan/material desynchronization before canvas encoding begins.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/canvas.py:135

            "keyframe target-canvas materials require plan.task='fl2va' or 'ref2va'"
        )
    semantic_indices = tuple(material.frame_index for material in keyframes)
    if semantic_indices not in MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES:
        raise ValueError(
            "MiniMax H3 keyframes must use one of the ordered frame_index signatures "
            f"{MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES!r}, got {semantic_indices!r}"
        )
    frame_count = plan.shape.get("frame_count")
    if isinstance(frame_count, bool) or not isinstance(frame_count, int):
        raise ValueError("keyframe preparation requires an integer frame_count")
    if frame_count <= 1:
        raise ValueError("keyframe preparation requires frame_count > 1")
    expected_pixels = tuple(
        frame_count - 1 if index == -1 else index for index in semantic_indices
    )
    resolved_pixels = tuple(material.resolved_frame_index for material in keyframes)
    if resolved_pixels != expected_pixels:
        raise ValueError(
            "keyframe resolved_frame_index values disagree with semantic "
            f"anchors: expected {expected_pixels!r}, got {resolved_pixels!r}"
        )
    return semantic_indices


def minimax_h3_prepared_keyframes(batch: Any, plan: Any) -> dict[str, Any]:
    """Resolve + prepare one or two first/last keyframes once per request.

    The target canvas is shared across keyframes and must already be frozen by
    the pre-queue probe/resolve hook.
    Top-level ``image`` / ``canvas_width`` / ``canvas_height`` keys mirror the
    first-keyframe payload for compatibility; per-keyframe entries live under
    ``images``.
    """
    keyframes = _keyframe_materials(plan)
    semantic_indices = _validate_keyframe_materials(plan, keyframes)
    cached = batch.extra.get(MINIMAX_H3_PREPARED_KEYFRAMES_EXTRA_KEY)

View on GitHub (pinned to 0132848349)

Solutions

1. Rebuild the keyframe materials from the current plan so resolved_frame_index matches tuple(frame_count-1 if i==-1 else i for i in semantic_indices)
2. Verify the keyframes list order matches semantic_indices order before calling the stage
3. Discard any stale per-request caches of keyframe materials when the plan shape or anchors change

Example fix

// before
keyframes = cached_keyframes  # from an older plan
result = minimax_h3_prepared_keyframes(plan, keyframes, batch)
// after
keyframes = build_keyframes_for_plan(plan)  # resolved_frame_index derived from current plan
result = minimax_h3_prepared_keyframes(plan, keyframes, batch)

expected = tuple(plan.frame_count - 1 if i == -1 else i for i in semantic_indices)
resolved = tuple(m.resolved_frame_index for m in keyframes)
assert resolved == expected, f'mismatch: {resolved} != {expected}'

def keyframes_match_plan(plan, keyframes, semantic_indices) -> bool:
    expected = tuple(plan.frame_count - 1 if i == -1 else i for i in semantic_indices)
    return tuple(m.resolved_frame_index for m in keyframes) == expected

When it happens

Trigger: Calling minimax_h3_prepared_keyframes (directly or via _encode_fl2va_keyframes/_encode_target_keyframes) with keyframe materials whose resolved_frame_index values were built from a different plan (different frame_count or semantic_frame_indices), or materials mutated after plan resolution.

Common situations: Reusing cached keyframe materials across requests with different plans, partial regeneration of keyframes after changing frame_count or semantic anchors, or a bug upstream that reorders the keyframes list relative to semantic_indices.

Related errors

• cached keyframe preparation disagrees with the resolved plan
• MiniMax H3 denoise state must be a mapping
• fl2va Qwen preparation requires one or two ordered images wi
• pipeline_cls must inherit from ComposedPipelineBase
• MiniMax-H3 adaln_t_table must have shape [N, D] with N >= 2,

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