sgl-project/sglang · error · ValueError

MiniMax H3 requires subblock_sparse_query_block_mask when Su

Error message

MiniMax H3 requires subblock_sparse_query_block_mask when SubBlock sparse attention is active

What it means

Raised during MiniMax H3 DiT attention when SubBlock sparse attention is enabled for a forward pass (sparse_will_run is true) but the required query block mask tensor was not provided. The sparse attention kernel needs subblock_sparse_query_block_mask to know which query blocks may be skipped, so running without it would silently produce dense (or wrong) results, hence the hard failure.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/minimax_h3.py:629

    else:
        if (
            attention._attention_backend_enum
            is AttentionBackendEnum.SUBBLOCK_SPARSE_ATTN
        ):
            impl = attention._attention_impl
            sparse_will_run = (
                cu_seqlens_host is not None
                and impl._sparse_ready(q, k)
                and any(
                    stop - start >= impl.schedule.min_seq_len
                    for start, stop in zip(
                        cu_seqlens_host[:-1],
                        cu_seqlens_host[1:],
                    )
                )
            )
            if sparse_will_run and subblock_sparse_query_block_mask is None:
                raise ValueError(
                    "MiniMax H3 requires subblock_sparse_query_block_mask "
                    "when SubBlock sparse attention is active"
                )
            out = attention._attention_impl.forward_varlen(
                q,
                k,
                v,
                cu_seqlens=cu_seqlens,
                max_seqlen=max_seqlen,
                cu_seqlens_host=cu_seqlens_host,
                first_segment_sparse_query_block_mask=(
                    subblock_sparse_query_block_mask
                ),
            )
        else:
            out = attention._attention_impl.forward_varlen(
                q,
                k,

View on GitHub (pinned to 0132848349)

Solutions

1. Ensure the mask builder runs and passes subblock_sparse_query_block_mask on every path where sparse attention can trigger
2. Check the condition computing sparse_will_run — if the run is actually dense, gate it so sparse is not considered active
3. If sparse attention is unwanted, disable the SubBlock sparse option in configuration
4. Add an assertion upstream where the mask is (not) constructed to fail closer to the cause

Example fix

// before
out = _run_attention_core_without_query_mask(q, k, v, ..., subblock_sparse_query_block_mask=None)
// after
assert not (sparse_will_run and subblock_sparse_query_block_mask is None)
out = _run_attention_core_without_query_mask(q, k, v, ..., subblock_sparse_query_block_mask=query_block_mask)

if sparse_attention_enabled and query_block_mask is None:
    raise RuntimeError("build subblock_sparse_query_block_mask before running sparse attention")

def has_sparse_query_mask(cfg) -> bool:
    return not cfg.sparse_enabled or cfg.subblock_sparse_query_block_mask is not None

When it happens

Trigger: Calling the MiniMax H3 attention core (via _run_attention_core_without_query_mask) with a sparse attention configuration active while subblock_sparse_query_block_mask=None in the arguments.

Common situations: Sparse-attention flags enabled in server args but the mask-building pipeline skipped (varlen/prefill path that bypasses mask construction), partial integration of a new sparse mode, or a caller refactoring that dropped the mask parameter.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• refiner cu_seqlens live text length must be in [1, {int(text
• subblock_sparse_query_block_mask must be a tensor
• bad compress_ratio {compress_ratio}
• indices must be on q's device {device}, got {indices.device}
• q must be torch.float8_e4m3fn, got {q.dtype}

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