sgl-project/sglang · error · ValueError

Invalid attention backend '{backend}'. Available options are

Error message

Invalid attention backend '{backend}'. Available options are: {[e.name.lower() for e in AttentionBackendEnum]}

What it means

After normalization (strip/lower, fa3|fa4->fa, cudnn_sdpa->torch_cudnn_sdpa), the backend name is looked up as AttentionBackendEnum[name.upper()]; an unknown name raises with the full list of valid enum members.

Source

Thrown at python/sglang/multimodal_gen/runtime/server_args/server_args.py:1023

                logger.info(
                    "Automatically set attention_backend=fa for LTX-2.3 one-stage on 1 GPU to preserve precision"
                )
                return
            self._set_default_attention_backend()

    @staticmethod
    def _normalize_attention_backend_name(backend: str) -> str:
        if not isinstance(backend, str):
            raise ValueError("Attention backend name must be a string")
        normalized = backend.strip().lower()
        if normalized in ("fa3", "fa4"):
            normalized = "fa"
        elif normalized == "cudnn_sdpa":
            normalized = "torch_cudnn_sdpa"
        try:
            return AttentionBackendEnum[normalized.upper()].name.lower()
        except KeyError:
            raise ValueError(
                f"Invalid attention backend '{backend}'. "
                f"Available options are: {[e.name.lower() for e in AttentionBackendEnum]}"
            ) from None

    @staticmethod
    def _parse_component_value_map(
        value: dict[str, Any] | str | None, *, option: str
    ) -> dict[str, str]:
        """Parse a ``component=value`` map, the same shape as component backends."""
        if value is None or value == "":
            return {}
        if isinstance(value, dict):
            return {str(k): str(v) for k, v in value.items()}
        if not isinstance(value, str):
            raise ValueError(
                f"{option} must be a dict or a comma-separated component=value string"
            )
        try:

View on GitHub (pinned to 0132848349)

Solutions

  1. Pick a name from the list printed in the error (e.g. [e.name.lower() for e in AttentionBackendEnum])
  2. Note the aliases: fa3/fa4 map to 'fa', cudnn_sdpa maps to 'torch_cudnn_sdpa'; use those canonical forms
  3. Check AttentionBackendEnum in the codebase for your installed version

Example fix

# before
ServerArgs(..., attention_backend="flash_att")
# after
ServerArgs(..., attention_backend="fa")
Defensive patterns

Strategy: validation

Validate before calling

names = {e.name.lower() for e in AttentionBackendEnum}
aliases = {'fa3': 'fa', 'fa4': 'fa', 'cudnn_sdpa': 'torch_cudnn_sdpa'}
norm = aliases.get(name.strip().lower(), name.strip().lower())
assert norm in names, f'unknown attention backend {name!r}'

Type guard

def is_valid_attention_backend(name: str) -> bool:
    n = name.strip().lower()
    n = {'fa3': 'fa', 'fa4': 'fa', 'cudnn_sdpa': 'torch_cudnn_sdpa'}.get(n, n)
    return n in {e.name.lower() for e in AttentionBackendEnum}

Prevention

When it happens

Trigger: Passing 'vit', 'trt', or any name not in AttentionBackendEnum as a global or per-component attention backend; using a backend name that only exists in a different framework (e.g. vLLM naming) or was renamed between versions.

Common situations: Version upgrades where a backend was renamed/removed; copy-pasting backend names from docs of a different library; typos not covered by the alias mapping.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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