sgl-project/sglang · error · RuntimeError

Unknown flash attention version {ver}

Error message

Unknown flash attention version {ver}

What it means

flash_attn_with_kvcache dispatches across FA2/FA3 implementations based on the ver argument; any value other than the recognized versions falls through to raise RuntimeError(f"Unknown flash attention version {ver}").

Source

Thrown at python/sglang/kernels/ops/attention/flash_attention.py:221

            softmax_scale=softmax_scale,
            causal=causal,
            window_size=window_size,
            softcap=softcap,
            num_splits=num_splits,
            pack_gqa=pack_gqa,
            sinks=sinks,
            score_mod=score_mod,
            aux_tensors=aux_tensors,
            sfq=sfq,
            sfk=sfk,
            sfv=sfv,
            rel_bias=rel_bias,
            rel_bias_prep_cache=rel_bias_prep_cache,
            return_softmax_lse=return_softmax_lse,
            out=out,
        )
    else:
        raise RuntimeError(f"Unknown flash attention version {ver}")


def flash_attn_varlen_func(
    q,
    k,
    v,
    cu_seqlens_q,
    cu_seqlens_k,
    max_seqlen_q=None,
    max_seqlen_k=None,
    seqused_q=None,
    seqused_k=None,
    page_table=None,
    softmax_scale=None,
    causal=False,
    qv=None,
    q_descale=None,
    k_descale=None,

View on GitHub (pinned to 0132848349)

Solutions

1. Pass a supported integer version (e.g. 2 or 3) for ver
2. If ver comes from config, cast to int and validate against supported versions before calling
3. Check the function's signature/docstring for the currently accepted ver values in your sglang version

Example fix

// before
out = flash_attn_with_kvcache(..., ver=int(os.getenv('FA_VER', '3')) if False else '3')
// after
out = flash_attn_with_kvcache(..., ver=3)

assert ver in (2, 3), f'unsupported flash attention version {ver!r}'

def is_supported_fa_ver(ver) -> bool:\n    return isinstance(ver, int) and ver in (2, 3)

When it happens

Trigger: Calling flash_attn_with_kvcache(..., ver=X) where X is not a supported version constant (e.g. a string like '3' instead of 3, or an unsupported number).

Common situations: Passing ver read from config/env as a string; version mismatch after upgrading sglang where supported version set changed.

Related errors

• k_cache can only be None when only_qv=True
• q can only be None when only_qv=True
• out is only supported for forward-only inference
• Unsupported content type ${header.content_type}
• Unknown serve backend {name!r}. Available values: {available

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