{"record":{"id":"24c8d0d8c379c908","repo":"unslothai/unsloth","slug":"unsupported-attention-backend-value-use-one-o","errorCode":null,"errorMessage":"Unsupported attention_backend '{value}'. Use one of: {', '.join(ATTN_ALIASES)}.","messagePattern":"Unsupported attention_backend '(.+?)'\\. Use one of: (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":400,"severity":"error","filePath":"studio/backend/core/inference/diffusion_attention.py","lineNumber":64,"sourceCode":"    \"flash3\": \"_flash_3_hub\",\n    \"flash4\": \"flash_4_hub\",\n    \"sage\": \"sage\",\n    \"xformers\": \"xformers\",\n    \"aiter\": \"aiter\",\n}\nATTN_ALIASES = (ATTN_AUTO,) + tuple(dict.fromkeys(_ALIASES))\n\n\ndef normalize_attention_backend(value: Optional[str]) -> Optional[str]:\n    \"\"\"Lower/strip a requested backend; None / \"\" / \"auto\" -> \"auto\". Raises ValueError for an\n    unsupported alias so a bad request is rejected cheaply.\"\"\"\n    if value is None:\n        return ATTN_AUTO\n    normalized = str(value).strip().lower()\n    if not normalized:\n        return ATTN_AUTO\n    if normalized not in ATTN_ALIASES:\n        raise ValueError(\n            f\"Unsupported attention_backend '{value}'. Use one of: {', '.join(ATTN_ALIASES)}.\"\n        )\n    return normalized\n\n\n# 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+.\n_ARCH_CAPABILITY: dict[str, tuple[tuple[int, int], Optional[tuple[int, int]]]] = {\n    \"_flash_3_hub\": ((9, 0), (10, 0)),  # FlashAttention 3 -> Hopper (SM90) only\n    \"flash_4_hub\": ((10, 0), None),  # FlashAttention 4 -> Blackwell (SM100)+\n}\n\n\ndef _cuda_capability() -> Optional[tuple[int, int]]:\n    \"\"\"(major, minor) compute capability of the active CUDA device, or None if unknown.\"\"\"\n    try:\n        import torch\n        if not torch.cuda.is_available():\n            return None","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/diffusion_attention.py#L46-L82","documentation":"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).","triggerScenarios":"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.","commonSituations":"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'.","solutions":["Use one of the accepted aliases: auto, native, sdpa, cudnn, flash, flash2, flash3, flash4, sage, xformers, aiter.","Use 'auto' (or omit / send empty string / null) to let the loader pick.","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."],"exampleFix":"# before\nengine.load(repo, attention_backend=\"flash_attention_2\")\n# after\nengine.load(repo, attention_backend=\"flash2\")  # or \"flash\" / \"auto\"","handlingStrategy":"validation","validationCode":"ATTN_ALIASES = {\"auto\", \"native\", \"sdpa\", \"cudnn\", \"flash\", \"flash2\", \"flash3\", \"flash4\", \"sage\", \"xformers\", \"aiter\"}\n\ndef valid_attention_backend(v: str | None) -> bool:\n    return v is None or str(v).strip().lower() in ATTN_ALIASES","typeGuard":"def is_attention_alias(v) -> bool:\n    return v is None or str(v).strip().lower() in {\n        \"auto\", \"native\", \"sdpa\", \"cudnn\", \"flash\", \"flash2\",\n        \"flash3\", \"flash4\", \"sage\", \"xformers\", \"aiter\",\n    }","tryCatchPattern":"try:\n    engine.load(repo, attention_backend=backend)\nexcept ValueError as e:\n    if \"Unsupported attention_backend\" in str(e):\n        engine.load(repo, attention_backend=\"auto\")  # explicit fallback policy\n    else:\n        raise","preventionTips":["Restrict the backend dropdown to the alias tuple; default to 'auto'.","Remember matching is case-insensitive but exact-word: 'flash_attention_2' and 'fa2' are invalid.","FA3 needs Hopper (SM90), FA4 needs Blackwell (SM100+) — pick by GPU arch or use auto."],"tags":["diffusion","attention-backend","validation","configuration"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}