sgl-project/sglang · error · ValueError

hybrid ref2va layout only supports first/last keyframe ancho

Error message

hybrid ref2va layout only supports first/last keyframe anchors, got resolved frame index {pixel_index}

What it means

In the hybrid ref2va layout, each reference block may anchor to a keyframe, but only the first (pixel index 0) and last (frame_count - 1) frames of the target video are valid anchors. The error reports the resolved frame index when a keyframe_frame_indices entry maps to any middle frame. This restriction exists because only first/last keyframe rows are materialized in the packed sequence.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/packed_sequence.py:504

    g[audio_sl, 0] = audio_t_grid.repeat(audio_channel)
    g[audio_sl.start : audio_sl.start + audio_t, 2] = float(w_grid[0])
    g[audio_sl.start + audio_t : audio_sl.stop, 2] = float(w_grid[-1])

    video_g = g[video_sl].view(latent_t, frame_rows, 3)
    video_g[:, :, 0] = _video_t_grid(latent_t, t_cursor)[:, None]
    video_g[:, :, 1:] = target_frame[None]

    for block_index, pixel_index in enumerate(resolved_keyframe_indices):
        sl = slice(
            keyframe_sl.start + block_index * frame_rows,
            keyframe_sl.start + (block_index + 1) * frame_rows,
        )
        if pixel_index == 0:
            cond_t = t_cursor
        elif frame_count is not None and pixel_index == frame_count - 1:
            cond_t = t_cursor + _temporal_position_span(latent_t) - _FRAME_RESCALE
        else:
            raise ValueError(
                "hybrid ref2va layout only supports first/last keyframe anchors, "
                f"got resolved frame index {pixel_index}"
            )
        g[sl, 0] = cond_t
        g[sl, 1:] = target_frame

    keyframe_img_pos = _range_for_slice(keyframe_sl)
    target_img_pos = _range_for_slice(video_sl)
    target_audio_pos = _range_for_slice(audio_sl)
    img_pos = _cat_ranges([keyframe_img_pos] + ref_img_pos_parts + [target_img_pos])
    audio_pos = _cat_ranges(ref_audio_pos_parts + [target_audio_pos])

    update_mask = torch.zeros(img_pos.shape[0], dtype=torch.bool)
    update_mask[keyframe_rows + ref_visual_rows :] = True
    audio_update_mask = torch.zeros(audio_pos.shape[0], dtype=torch.bool)
    audio_update_mask[ref_audio_rows:] = True
    text_pos = torch.arange(0, text_len)

View on GitHub (pinned to 0132848349)

Solutions

1. Restrict keyframe_frame_indices to values resolving to the first or last frame (typically 0 and/or frame_count-1).
2. Clamp/round requested anchor indices to the nearest endpoint before calling.
3. For mid-video conditioning, split the clip so the desired frame becomes an endpoint of a segment.

Example fix

# before
keyframe_frame_indices = [0, 6, 11]  # 6 is a middle frame -> error

# after
keyframe_frame_indices = [0, 11]  # first and last frames only

anchors = [i for i in keyframe_frame_indices if i in (0, frame_count - 1)]
if len(anchors) != len(keyframe_frame_indices or []):
    raise ValueError("only first/last frame anchors supported")

def valid_hybrid_anchors(indices, frame_count) -> bool:
    return all(i == 0 or i == frame_count - 1 for i in indices)

When it happens

Trigger: Passing keyframe_frame_indices that resolve (via the keyframe-condition index resolution) to a frame index other than 0 or frame_count-1 — e.g. indices [1], [0, 5, 10] on a 12-frame clip where 5 is a middle frame.

Common situations: Sampling 'representative' middle frames as conditioning anchors; off-by-one errors producing frame_count instead of frame_count-1; a UI letting users pick arbitrary keyframes on a timeline.

Related errors

• generated MiniMax H3 MP4 frame rate must be {MINIMAX_H3_SUPP
• MiniMax-H3 adaln_t_table must have shape [N, D] with N >= 2,
• MiniMax H3 AdaLN cache has invalid timestep plans
• TP size must be positive.
• num_attention_heads must be positive.

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