sgl-project/sglang · error · ValueError

Only ver=3 is supported for MUSA FA3.

Error message

Only ver=3 is supported for MUSA FA3.

What it means

SGLang's MUSA flash-attention wrapper, flash_attn_with_kvcache, is a thin reimplementation of the v3 API for Moore Threads MUSA GPUs and only implements the ver=3 code path; any other ver argument is rejected up front.

Source

Thrown at python/sglang/srt/hardware_backend/musa/attention/flashattention_backend.py:160

    softmax_scale: Optional[float] = None,
    causal: bool = False,
    window_size: Tuple[int, int] = (-1, -1),
    attention_chunk: int = 0,
    softcap: float = 0.0,
    rotary_interleaved: bool = True,
    scheduler_metadata: Optional[torch.Tensor] = None,
    num_splits: int = 0,
    pack_gqa=None,
    sm_margin: int = 0,
    return_softmax_lse: bool = False,
    sinks=None,
    score_mod=None,
    aux_tensors=None,
    ver=3,
):
    """MUSA flash_attn_with_kvcache wrapper that auto-injects scheduler_metadata."""
    if ver != 3:
        raise ValueError("Only ver=3 is supported for MUSA FA3.")

    if scheduler_metadata is None and _CURRENT_BACKEND is not None:
        backend = _CURRENT_BACKEND
        # Ensure backend has been properly set up for this call
        if backend._current_layer is not None:
            page_size = k_cache.shape[1] if k_cache is not None else 1
            scheduler_metadata = _compute_scheduler_metadata(
                backend=backend,
                cu_seqlens_q=cu_seqlens_q,
                cu_seqlens_k_new=cu_seqlens_k_new,
                cache_seqlens=cache_seqlens,
                max_seqlen_q=max_seqlen_q,
                page_size=page_size,
                causal=causal,
                window_size=window_size,
                num_splits=num_splits,
            )

View on GitHub (pinned to 0132848349)

Solutions

1. Pass ver=3 or simply omit the argument (default is ver=3)
2. If you need FA2-style behavior on MUSA, use the non-FA3 MUSA backend path instead of this wrapper
3. Audit copied kernel code for hardcoded ver=2

Example fix

# before
flash_attn_with_kvcache(q, k, v, ..., ver=2)
# after
flash_attn_with_kvcache(q, k, v, ..., ver=3)  # or omit ver

ver = 3  # MUSA wrapper only implements ver=3
if ver != 3:
    raise ValueError("MUSA FA3 wrapper requires ver=3")
out = flash_attn_with_kvcache(q, k, v, ..., ver=ver)

try:
    out = flash_attn_with_kvcache(..., ver=requested_ver)
except ValueError as e:
    if "ver=3" in str(e):
        out = flash_attn_with_kvcache(..., ver=3)  # retry with supported ver
    else:
        raise

When it happens

Trigger: Calling flash_attn_with_kvcache(..., ver=2) (or any non-3 value) — usually code written against the upstream flash-attn API that explicitly passes ver=2, or a copied attention kernel defaulting ver differently.

Common situations: Porting attention backends from CUDA FA2 to MUSA; shared code paths that select ver based on capability detection and land on 2; third-party kernels calling the wrapper with explicit ver.

Related errors

• Can not import FA3 in sgl_kernel. Please check your installa
• v_cache must be provided
• k_cache can only be None when only_qv=True
• q can only be None when only_qv=True
• q must be provided unless qv is provided with only_qv=True

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