mudler/LocalAI · error · ValueError

attention_backend must be one of: {choices}

Error message

attention_backend must be one of: {choices}

What it means

Raised by attention_overrides() in longcat-video when the requested attention_backend key is absent from the ATTENTION_OVERRIDES dict. The error message enumerates the valid choices so the user can correct the name. The original KeyError is chained.

Source

Thrown at backend/python/longcat-video/longcat_utils.py:122

def require_float(value, name, minimum=None, maximum=None):
    try:
        parsed = float(value)
    except (TypeError, ValueError) as err:
        raise ValueError(f"{name} must be a number") from err
    if minimum is not None and parsed < minimum:
        raise ValueError(f"{name} must be at least {minimum}")
    if maximum is not None and parsed > maximum:
        raise ValueError(f"{name} must be at most {maximum}")
    return parsed


def attention_overrides(name):
    try:
        return dict(ATTENTION_OVERRIDES[name])
    except KeyError as err:
        choices = ", ".join(ATTENTION_OVERRIDES)
        raise ValueError(f"attention_backend must be one of: {choices}") from err


def _model_name_from_directory(path):
    for filename in ("model_index.json", "config.json"):
        config_path = os.path.join(path, filename)
        try:
            with open(config_path, "r", encoding="utf-8") as config_file:
                model_name = json.load(config_file).get("model_name", "")
        except (FileNotFoundError, OSError, ValueError, TypeError):
            continue
        if model_name:
            return model_name
    return ""


def normalize_model_source(model):
    value = model.rstrip("/")
    for prefix in ("huggingface://", "hf://"):

View on GitHub (pinned to 44413a9d06)

Solutions

1. Use one of the choices listed in the error message verbatim
2. Strip/normalize whitespace and check underscore vs hyphen spelling
3. Check the ATTENTION_OVERRIDES dict in longcat_utils.py for the exact keys this version supports

Example fix

# before
attention_overrides('flash-attn2')  # ValueError: must be one of: ...

# after
attention_overrides('flash_attn2')  # exact key from ATTENTION_OVERRIDES

from longcat_utils import ATTENTION_OVERRIDES
backend = (request.attention_backend or '').strip()
if backend not in ATTENTION_OVERRIDES:
    raise ValueError(f'unsupported attention_backend {backend!r}; choose from {sorted(ATTENTION_OVERRIDES)}')
overrides = attention_overrides(backend)

def is_valid_attention_backend(name: str) -> bool:
    return name in ATTENTION_OVERRIDES

try:
    ov = attention_overrides(name)
except ValueError as err:
    # message already lists valid choices; surface it to the user
    return error_response(str(err))

When it happens

Trigger: Calling attention_overrides(name) with a backend string that is not a key in ATTENTION_OVERRIDES — typo like 'sdpa ' (trailing space), 'flash-attn' vs 'flash_attn' underscore/hyphen mismatch, or a backend name from a newer/older version.

Common situations: Copy-pasted config from another project using different naming (flashattn vs flash_attn2), version drift where a backend key was renamed, or case sensitivity ('SDPA' vs 'sdpa').

Related errors

• resolution must be 480p or 720p
• start_image is not a readable staged file
• num_frames must not be negative
• audio input requires a LongCat-Video-Avatar-1.5 model
• base_model must point to a LongCat-Video checkpoint

AI-assisted analysis of mudler/LocalAI@44413a9d06 (2026-08-15). Data as JSON: /api/errors/22ea80d3ba083224. Report an issue: GitHub.