sgl-project/sglang · error · ValueError

spt requires dq_write_order to be provided

Error message

spt requires dq_write_order to be provided

What it means

Raised when spt mode is enabled but dq_write_order is not supplied. The spt kernel path needs the dq write-order metadata to sequence gradient writes correctly.

Source

Thrown at python/sglang/kernels/ops/attention/flash_attn/cute/block_sparsity.py:494

        tensors.dq_write_order,
        tuple(mask_idx.shape),
        context,
        hint,
        mask_cnt.device,
    )
    dq_write_order_full = _check_and_expand_metadata_tensor(
        "dq_write_order_full",
        tensors.dq_write_order_full,
        tuple(full_idx.shape) if full_idx is not None else expected_index_shape,
        context,
        hint,
        mask_cnt.device,
    )
    spt = tensors.spt
    if spt is not None and not isinstance(spt, bool):
        raise ValueError("spt must be a bool when provided")
    if spt is not None and dq_write_order is None:
        raise ValueError("spt requires dq_write_order to be provided")

    return BlockSparseTensorsTorch(
        mask_block_cnt=mask_cnt,
        mask_block_idx=mask_idx,
        full_block_cnt=full_cnt,
        full_block_idx=full_idx,
        cu_total_m_blocks=tensors.cu_total_m_blocks,
        cu_block_idx_offsets=tensors.cu_block_idx_offsets,
        block_size=tensors.block_size,
        dq_write_order=dq_write_order,
        dq_write_order_full=dq_write_order_full,
        spt=spt,
    )


def is_block_sparsity_enabled(tensors: BlockSparseTensorsTorch) -> bool:
    return any(t is not None for t in (tensors.full_block_cnt, tensors.mask_block_cnt))

View on GitHub (pinned to 0132848349)

Solutions

1. Provide dq_write_order as an int32 CUDA tensor with shape equal to mask_block_idx's shape
2. Or unset spt (leave None/False) if the spt mode is not intended

Example fix

// before
tensors = BlockSparseTensorsTorch(cnt, idx, spt=True)
// after
order = make_dq_write_order(idx.shape)  # int32, cuda
tensors = BlockSparseTensorsTorch(cnt, idx, spt=True, dq_write_order=order)

if tensors.spt is not None:
    assert tensors.dq_write_order is not None, 'spt requires dq_write_order'

When it happens

Trigger: Setting BlockSparseTensorsTorch(spt=True) without dq_write_order, then calling normalize_block_sparse_tensors (e.g. via normalize_block_sparse_config_bwd).

Common situations: Enabling spt for the backward pass but only preparing the forward's mask/full tensors.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• mask_block_cnt and mask_block_idx must be provided for block
• spt must be a bool when provided
• Usage: sglang serve --model-path <model-name-or-path> [addit
• Error: --model-path is required. Please provide the path to
• v_cache must be provided

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