sgl-project/sglang · error · ValueError

Attention backend override '{target}' resolved to '{resolved

Error message

Attention backend override '{target}' resolved to '{resolved}' on {type(layer).__name__}; refusing the request instead of silently falling back.

What it means

When an attention backend override is requested on a layer, the resolved backend enum must exactly equal the requested one. The resolver picked a different backend (e.g. the requested enum is an alias or was remapped because it is not in the layer's supported_attention_backends), and rather than silently using a different kernel the code raises.

Source

Thrown at python/sglang/multimodal_gen/runtime/layers/attention/layer.py:301

            self._cache_key = cache_key
        return self._meta


def prepare_attention_backend_override(
    layer: nn.Module, target: AttentionBackendEnum
) -> None:
    """Build and cache the impl for ``target``; may raise, mutates nothing."""
    if target in layer._attn_impl_by_backend:
        return
    backend_cls = get_attn_backend(
        layer.head_size,
        layer.dtype,
        supported_attention_backends=layer._supported_attention_backends,
        selected_attention_backend=target,
    )
    resolved = backend_cls.get_enum()
    if resolved is not target:
        raise ValueError(
            f"Attention backend override '{target}' resolved to '{resolved}' on "
            f"{type(layer).__name__}; refusing the request instead of silently "
            "falling back."
        )
    impl = backend_cls.get_impl_cls()(**layer._attn_impl_ctor_kwargs)
    wrap_attention_impl_forward(impl)
    layer._attn_impl_by_backend[target] = impl


def apply_attention_backend_override(
    layer: nn.Module, target: AttentionBackendEnum | None
) -> None:
    """Flip to a prepared impl (None = construction default); cannot fail."""
    target = target or layer._default_attn_backend
    if target is layer.backend:
        return
    layer.attn_impl = layer._attn_impl_by_backend[target]
    layer.backend = target

View on GitHub (pinned to 0132848349)

Solutions

1. Check layer._supported_attention_backends and request a backend that is directly supported (resolved enum == requested enum)
2. Update the override value to the new canonical enum name after a rename/merge in a newer sglang version
3. If you maintain the layer, add the desired backend to supported_attention_backends so no substitution occurs
4. As a workaround, remove the override and let the default backend selection apply (accepting it may not be the kernel you wanted)

Example fix

// before
layer._maybe_override_attention_backend(AttentionBackendEnum.OLD_ALIAS)
// after
assert target in layer._supported_attention_backends
layer._maybe_override_attention_backend(target)

if target not in layer._supported_attention_backends:
    raise ValueError(f"backend {target} unsupported; pick from {layer._supported_attention_backends}")

def resolves_to_self(layer, target: AttentionBackendEnum) -> bool:
    return target in layer._supported_attention_backends

try:
    layer._maybe_override_attention_backend(target)
except ValueError as e:
    if "resolved to" in str(e):
        logger.warning("override %s not directly supported; using default backend", target)
    else:
        raise

When it happens

Trigger: Calling prepare_attention_backend_override (via _maybe_override_attention_backend or layer forward with an override) with a target AttentionBackendEnum that the layer's supported_attention_backends set maps to a different concrete backend class, so backend_cls.get_enum() != target.

Common situations: Requesting a backend alias (e.g. an alias resolving to FLASHINFER when FA was asked for); layer only supports a subset of backends so the resolver substitutes the default; version upgrade where a backend enum was merged/renamed and old override values now resolve elsewhere; tests pinning an old enum name.

Related errors

• Block sparse tensors{context} require BLOCK_SIZE_KV={base_n_
• num_heads must be divisible by num_epi_subtiles
• num_heads // num_epi_subtiles must be divisible by 4 (FMA un
• sparse_attn_v4_paged_decode expects fp16/bf16 q, got {q.dtyp
• kv_scales supplied but unified_kv is {unified_kv.dtype}, exp

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