sgl-project/sglang · error · NotImplementedError

PD disaggregation for MiniMax sparse layers with index value

Error message

PD disaggregation for MiniMax sparse layers with index value (index_kv_pool) is not yet supported; only K-only sparse layers are.

What it means

When preparing disaggregation state transfer args, setup_state_kv_args detects a MiniMaxSparseKVPool and refuses to transfer state if the pool carries an index value pool (index_kv_pool). Only K-only sparse layers have an implemented state-transfer path (StateType.MINIMAX_INDEX_K), so index-value models raise NotImplementedError.

Source

Thrown at python/sglang/srt/disaggregation/utils.py:1008

    kv_args.state_data_ptrs = []
    kv_args.state_data_lens = []
    kv_args.state_item_lens = []
    kv_args.state_dim_per_tensor = []
    kv_args.state_slice_outer_counts = []
    kv_args.state_layer_ids = []
    kv_args.is_hybrid_mla_backend = False
    kv_args.state_conv_shard_groups = []

    if isinstance(token_to_kv_pool, MHATokenToKVPoolMXFP8):
        append_state_component(
            kv_args,
            StateType.BLOCK_SCALE,
            *token_to_kv_pool.get_kv_scale_buf_infos(),
        )

    if isinstance(token_to_kv_pool, MiniMaxSparseKVPool):
        if token_to_kv_pool.index_kv_pool is not None:
            raise NotImplementedError(
                "PD disaggregation for MiniMax sparse layers with index value "
                "(index_kv_pool) is not yet supported; only K-only sparse layers are."
            )
        if token_to_kv_pool.index_k_pool is not None:
            dp, dl, il = token_to_kv_pool.get_index_k_state_buf_infos()
            append_state_component(kv_args, StateType.MINIMAX_INDEX_K, dp, dl, il)
    elif hasattr(token_to_kv_pool, "get_state_buf_infos"):
        data_ptrs, data_lens, item_lens = token_to_kv_pool.get_state_buf_infos()

        # DeepSeekV4TokenToKVPool inherits BaseSWAKVPool; its heterogeneous
        # state list is described per-entry via get_state_buf_infos.
        if isinstance(token_to_kv_pool, BaseSWAKVPool):
            append_state_component(
                kv_args, StateType.SWA, data_ptrs, data_lens, item_lens
            )
            # MXFP8 KV: each sub-pool's block scales ride as their own component
            # so they inherit the index payload of the KV they describe.
            # Only the concrete SWAKVPool owns a full sub-pool; other

View on GitHub (pinned to 0132848349)

Solutions

Use a K-only sparse-layer MiniMax configuration (disable index value pool) if the model variant allows it
Run the model without PD disaggregation (single-node serving) until index-value transfer is supported
Track/upgrade to an SGLang release that implements index_kv_pool state transfer

Example fix

// before
MiniMaxSparseKVPool(..., index_kv_pool=IndexKVPool(...))  # with --disaggregation-prefill
// after
MiniMaxSparseKVPool(..., index_kv_pool=None)  # K-only sparse layers, disaggregation OK

Defensive patterns

Strategy: type-guard

Type guard

def supports_disagg(pool) -> bool:
    return not (isinstance(pool, MiniMaxSparseKVPool) and pool.index_kv_pool is not None)

Try / catch

try:
    setup_state_kv_args(...)
except NotImplementedError as e:
    logger.error("Model variant unsupported for PD disaggregation: %s", e)
    sys.exit(1)

Prevention

Check index_kv_pool is None before enabling disaggregation on MiniMax sparse models
Watch release notes for index-value transfer support

When it happens

Trigger: Initializing a disaggregated scheduler (_init_kv_manager) for a MiniMax sparse-attention model whose KV pool was constructed with index_kv_pool set (index-value sparse layers) rather than index_k_pool only.

Common situations: Enabling PD disaggregation on a MiniMax sparse-attention variant that uses index-value layers; upgrading a model config that now enables index value heads; feature not yet implemented in this SGLang version.

Related errors

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