sgl-project/sglang · error · ValueError

Invalid attention backend for {current_platform.device_name}

Error message

Invalid attention backend for {current_platform.device_name}

What it means

Raised when current_platform.get_attn_backend_cls_str returns a falsy value, meaning the selected backend name has no registered implementation class string for the active platform/device. It signals a backend/platform mismatch rather than a missing module.

Source

Thrown at python/sglang/multimodal_gen/runtime/layers/attention/selector.py:341

    elif selected_backend is None and len(supported_attention_backends) == 1:
        selected_backend = next(iter(supported_attention_backends))
    elif selected_backend is not None and not _is_backend_supported(
        selected_backend, supported_attention_backends
    ):
        supported_attention_backends_str = [
            supported_attention_backend.__str__()
            for supported_attention_backend in supported_attention_backends
        ]
        raise ValueError(
            f"Attention backend '{selected_backend}' is not supported by this "
            f"attention layer; supported backends: {supported_attention_backends_str}"
        )

    attention_cls = current_platform.get_attn_backend_cls_str(
        selected_backend, head_size, dtype
    )
    if not attention_cls:
        raise ValueError(
            f"Invalid attention backend for {current_platform.device_name}"
        )
    return cast(type[AttentionBackend], resolve_obj_by_qualname(attention_cls))


def _is_backend_supported(
    selected_backend: AttentionBackendEnum,
    supported_attention_backends: set[AttentionBackendEnum],
) -> bool:
    if selected_backend in supported_attention_backends:
        return True
    if selected_backend == AttentionBackendEnum.TORCH_CUDNN_SDPA:
        return AttentionBackendEnum.TORCH_SDPA in supported_attention_backends
    if selected_backend == AttentionBackendEnum.DYNAMIC_CUDNN_SDPA:
        return (
            AttentionBackendEnum.FA in supported_attention_backends
            and AttentionBackendEnum.TORCH_SDPA in supported_attention_backends
        )

View on GitHub (pinned to 0132848349)

Solutions

1. Use a backend supported by current_platform.device_name (check the platform's backend mapping)
2. Fix the backend name spelling / update to the new name after a version change
3. Set the correct platform/device env so detection matches your hardware

Example fix

# before (on CPU)
get_attn_backend("fa3", ...)
# after
get_attn_backend("torch_native" if current_platform.device_name=="cpu" else "fa3", ...)

cls_str = current_platform.get_attn_backend_cls_str(selected_backend, head_size, dtype)
if not cls_str:\n    raise SystemExit(f'{selected_backend} unavailable on {current_platform.device_name}')

try:\n    backend_cls = get_attn_backend(name, ...)\nexcept ValueError as e:\n    if 'Invalid attention backend' in str(e):\n        # pick a platform-portable default\n        backend_cls = get_attn_backend('triton', ...)

When it happens

Trigger: Calling _cached_get_attn_backend/get_attn_backend with a backend name that the current platform's registry does not map to any class (e.g. a CUDA-only backend on CPU/NPU, or a typo'd/renamed backend name).

Common situations: Running on a non-CUDA device with a CUDA backend name; backend renamed between versions; platform detection picking the wrong device.

Related errors

• flashinfer_sparse_mla supports only GLM DSA with FP8 KV cach
• GLM DSA with FP8 KV cache on NVIDIA SM120/SM121 supports onl
• MiniMax-H3 ring parallelism requires the FlashAttention back
• AITer backend does not have a metadata builder.
• AITer backend requires num_heads ({num_heads}) to be a multi

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