{"record":{"id":"7b37cbc1a82f8b76","repo":"sgl-project/sglang","slug":"minimax-h3-requires-subblock-sparse-query-block-ma","errorCode":null,"errorMessage":"MiniMax H3 requires subblock_sparse_query_block_mask when SubBlock sparse attention is active","messagePattern":"MiniMax H3 requires subblock_sparse_query_block_mask when SubBlock sparse attention is active","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/minimax_h3.py","lineNumber":629,"sourceCode":"    else:\n        if (\n            attention._attention_backend_enum\n            is AttentionBackendEnum.SUBBLOCK_SPARSE_ATTN\n        ):\n            impl = attention._attention_impl\n            sparse_will_run = (\n                cu_seqlens_host is not None\n                and impl._sparse_ready(q, k)\n                and any(\n                    stop - start >= impl.schedule.min_seq_len\n                    for start, stop in zip(\n                        cu_seqlens_host[:-1],\n                        cu_seqlens_host[1:],\n                    )\n                )\n            )\n            if sparse_will_run and subblock_sparse_query_block_mask is None:\n                raise ValueError(\n                    \"MiniMax H3 requires subblock_sparse_query_block_mask \"\n                    \"when SubBlock sparse attention is active\"\n                )\n            out = attention._attention_impl.forward_varlen(\n                q,\n                k,\n                v,\n                cu_seqlens=cu_seqlens,\n                max_seqlen=max_seqlen,\n                cu_seqlens_host=cu_seqlens_host,\n                first_segment_sparse_query_block_mask=(\n                    subblock_sparse_query_block_mask\n                ),\n            )\n        else:\n            out = attention._attention_impl.forward_varlen(\n                q,\n                k,","sourceCodeStart":611,"sourceCodeEnd":647,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/minimax_h3.py#L611-L647","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the mask builder runs and passes subblock_sparse_query_block_mask on every path where sparse attention can trigger","Check the condition computing sparse_will_run — if the run is actually dense, gate it so sparse is not considered active","If sparse attention is unwanted, disable the SubBlock sparse option in configuration","Add an assertion upstream where the mask is (not) constructed to fail closer to the cause"],"exampleFix":"// before\nout = _run_attention_core_without_query_mask(q, k, v, ..., subblock_sparse_query_block_mask=None)\n// after\nassert not (sparse_will_run and subblock_sparse_query_block_mask is None)\nout = _run_attention_core_without_query_mask(q, k, v, ..., subblock_sparse_query_block_mask=query_block_mask)","handlingStrategy":"validation","validationCode":"if sparse_attention_enabled and query_block_mask is None:\n    raise RuntimeError(\"build subblock_sparse_query_block_mask before running sparse attention\")","typeGuard":"def has_sparse_query_mask(cfg) -> bool:\n    return not cfg.sparse_enabled or cfg.subblock_sparse_query_block_mask is not None","tryCatchPattern":null,"preventionTips":["Centralize mask construction so every sparse path receives the mask","Assert mask presence in tests covering the varlen/prefill path"],"tags":["minimax-h3","sparse-attention","dit","mask-required"],"backgroundTag":"missing-required-argument","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}