unslothai/unsloth · error · ValueError

Unsupported attention_backend '{value}'. Use one of: {', '.j

Error message

Unsupported attention_backend '{value}'. Use one of: {', '.join(ATTN_ALIASES)}.

What it means

normalize_attention_backend() lowercases/strips the requested attention backend and rejects anything not in ATTN_ALIASES: auto, native, sdpa, cudnn, flash/flash2, flash3, flash4, sage, xformers, aiter. The check is intentionally cheap (string membership) so a bad request is rejected before any model interaction; it only validates the alias, not whether the kernel exists for your GPU (that is gated separately by CUDA arch ranges).

Source

Thrown at studio/backend/core/inference/diffusion_attention.py:64

    "flash3": "_flash_3_hub",
    "flash4": "flash_4_hub",
    "sage": "sage",
    "xformers": "xformers",
    "aiter": "aiter",
}
ATTN_ALIASES = (ATTN_AUTO,) + tuple(dict.fromkeys(_ALIASES))


def normalize_attention_backend(value: Optional[str]) -> Optional[str]:
    """Lower/strip a requested backend; None / "" / "auto" -> "auto". Raises ValueError for an
    unsupported alias so a bad request is rejected cheaply."""
    if value is None:
        return ATTN_AUTO
    normalized = str(value).strip().lower()
    if not normalized:
        return ATTN_AUTO
    if normalized not in ATTN_ALIASES:
        raise ValueError(
            f"Unsupported attention_backend '{value}'. Use one of: {', '.join(ATTN_ALIASES)}."
        )
    return normalized


# Backends diffusers validates by package at set time but whose kernels need a specific CUDA arch at run time. Gate by a (min, max-exclusive) capability range: FA3 is Hopper-SM90 only, FA4 is Blackwell+.
_ARCH_CAPABILITY: dict[str, tuple[tuple[int, int], Optional[tuple[int, int]]]] = {
    "_flash_3_hub": ((9, 0), (10, 0)),  # FlashAttention 3 -> Hopper (SM90) only
    "flash_4_hub": ((10, 0), None),  # FlashAttention 4 -> Blackwell (SM100)+
}


def _cuda_capability() -> Optional[tuple[int, int]]:
    """(major, minor) compute capability of the active CUDA device, or None if unknown."""
    try:
        import torch
        if not torch.cuda.is_available():
            return None

View on GitHub (pinned to 203007d190)

Solutions

1. Use one of the accepted aliases: auto, native, sdpa, cudnn, flash, flash2, flash3, flash4, sage, xformers, aiter.
2. Use 'auto' (or omit / send empty string / null) to let the loader pick.
3. For FlashAttention 3/4, also verify your GPU arch (FA3 needs Hopper SM90, FA4 needs Blackwell SM100+) — a valid alias on the wrong arch fails later, not here.

Example fix

# before
engine.load(repo, attention_backend="flash_attention_2")
# after
engine.load(repo, attention_backend="flash2")  # or "flash" / "auto"

ATTN_ALIASES = {"auto", "native", "sdpa", "cudnn", "flash", "flash2", "flash3", "flash4", "sage", "xformers", "aiter"}

def valid_attention_backend(v: str | None) -> bool:
    return v is None or str(v).strip().lower() in ATTN_ALIASES

def is_attention_alias(v) -> bool:
    return v is None or str(v).strip().lower() in {
        "auto", "native", "sdpa", "cudnn", "flash", "flash2",
        "flash3", "flash4", "sage", "xformers", "aiter",
    }

try:
    engine.load(repo, attention_backend=backend)
except ValueError as e:
    if "Unsupported attention_backend" in str(e):
        engine.load(repo, attention_backend="auto")  # explicit fallback policy
    else:
        raise

When it happens

Trigger: Passing attention_backend='flash-attention', 'fa2', 'FlashAttention2', or any string outside the alias tuple — note the value is lowercased before matching, so case is fine, but hyphenated or abbreviated names are not aliases.

Common situations: Copying backend names from diffusers docs ('flash_attention_2') or vLLM-style configs into this API; version drift after aliases were renamed; typos like 'spar' for 'sage'.

Related errors

• Unsupported transformer_cache '{value}'. Use one of: off, au
• gradient_accumulation_steps must be >= 1
• resolution must be a multiple of 8 and >= 64
• Add a Provider connection block before running this recipe.
• Unknown model_kind '{model_kind}'. Expected one of {sorted(_

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/24c8d0d8c379c908. Report an issue: GitHub.