What causes "seq_len {seq_len} < used rows {used}" in sgl-project/sglang?

Omit seq_len and let the builder derive it with alignment padding.

sgl-project/sglang · error · ValueError

seq_len {seq_len} < used rows {used}

Error message

seq_len {seq_len} < used rows {used}

What it means

The builder computes an alignment-padded seq_len (rounded up to MINIMAX_H3_PACKED_SEQUENCE_ALIGNMENT) from the used row count, or accepts a caller-supplied seq_len; it then asserts seq_len >= used. The check fires when an explicitly passed seq_len is smaller than the rows the layout actually needs (text + keyframe + all reference blocks).

Source

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

        keyframe_frame_indices=keyframe_frame_indices,
    )
    resolved_keyframe_indices = _resolve_keyframe_frame_indices(
        keyframe_indices,
        frame_count=frame_count,
    )
    keyframe_rows = len(keyframe_indices) * frame_rows
    video_rows = latent_t * frame_rows
    audio_rows = audio_t * audio_channel
    ref_rows = ref_visual_rows + ref_audio_rows
    used = text_len + keyframe_rows + ref_rows + audio_rows + video_rows
    if seq_len is None:
        seq_len = (
            (used + MINIMAX_H3_PACKED_SEQUENCE_ALIGNMENT - 1)
            // MINIMAX_H3_PACKED_SEQUENCE_ALIGNMENT
            * MINIMAX_H3_PACKED_SEQUENCE_ALIGNMENT
        )
    if seq_len < used:
        raise ValueError(f"seq_len {seq_len} < used rows {used}")

    text_sl = slice(0, text_len)
    keyframe_sl = slice(text_len, text_len + keyframe_rows)
    cursor = keyframe_sl.stop
    block_slices: list[dict[str, object]] = []
    for item in parsed:
        kind = str(item["kind"])
        if kind == "image":
            rows = int(item["rows"])
            visual_sl = slice(cursor, cursor + rows)
            cursor = visual_sl.stop
            block_slices.append({**item, "visual_sl": visual_sl})
        elif kind == "audio":
            rows = int(item["audio_rows"])
            audio_sl = slice(cursor, cursor + rows)
            cursor = audio_sl.stop
            block_slices.append({**item, "audio_sl": audio_sl})
        else:

View on GitHub (pinned to 0132848349)

Solutions

Omit seq_len and let the builder derive it with alignment padding.
Recompute seq_len from the same inputs (text_len, latent shape, all ref_blocks) after any change to the media list.
If truncation is intended, reduce ref_blocks or latent resolution instead of forcing a smaller seq_len.

Example fix

# before
out = minimax_h3_packed_sequence_ref2va_blocks(..., seq_len=old_len)

# after
out = minimax_h3_packed_sequence_ref2va_blocks(...)  # seq_len derived + aligned

Defensive patterns

Strategy: validation

Validate before calling

# Let the builder derive seq_len; if you must pass it, verify:
from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.packed_sequence import MINIMAX_H3_PACKED_SEQUENCE_ALIGNMENT
assert seq_len is None or seq_len >= used_rows_estimate, "seq_len smaller than required rows"

Try / catch

try:
    layout = minimax_h3_packed_sequence_ref2va_blocks(..., seq_len=seq_len)
except ValueError as e:
    if "seq_len" in str(e):
        layout = minimax_h3_packed_sequence_ref2va_blocks(...)  # retry with derived seq_len
    else:
        raise

Prevention

Never hand-compute seq_len; derive it or omit it.
Recompute any cached seq_len whenever ref_blocks or latent dims change.

When it happens

Trigger: Passing a custom seq_len (rather than letting it be derived) that is less than the computed `used` rows — e.g. seq_len computed from a stale latent shape or from only some of the ref_blocks.

Common situations: Reusing a seq_len cached from an earlier request with fewer media blocks; computing seq_len with a different patch size or alignment constant than the packer; trimming seq_len to fit a KV budget without recomputing required rows.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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