{"record":{"id":"bc2c2af2c02022b1","repo":"sgl-project/sglang","slug":"attention-backend-override-target-resolved-to","errorCode":null,"errorMessage":"Attention backend override '{target}' resolved to '{resolved}' on {type(layer).__name__}; refusing the request instead of silently falling back.","messagePattern":"Attention backend override '(.+?)' resolved to '(.+?)' on (.+?); refusing the request instead of silently falling back\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/layers/attention/layer.py","lineNumber":301,"sourceCode":"            self._cache_key = cache_key\n        return self._meta\n\n\ndef prepare_attention_backend_override(\n    layer: nn.Module, target: AttentionBackendEnum\n) -> None:\n    \"\"\"Build and cache the impl for ``target``; may raise, mutates nothing.\"\"\"\n    if target in layer._attn_impl_by_backend:\n        return\n    backend_cls = get_attn_backend(\n        layer.head_size,\n        layer.dtype,\n        supported_attention_backends=layer._supported_attention_backends,\n        selected_attention_backend=target,\n    )\n    resolved = backend_cls.get_enum()\n    if resolved is not target:\n        raise ValueError(\n            f\"Attention backend override '{target}' resolved to '{resolved}' on \"\n            f\"{type(layer).__name__}; refusing the request instead of silently \"\n            \"falling back.\"\n        )\n    impl = backend_cls.get_impl_cls()(**layer._attn_impl_ctor_kwargs)\n    wrap_attention_impl_forward(impl)\n    layer._attn_impl_by_backend[target] = impl\n\n\ndef apply_attention_backend_override(\n    layer: nn.Module, target: AttentionBackendEnum | None\n) -> None:\n    \"\"\"Flip to a prepared impl (None = construction default); cannot fail.\"\"\"\n    target = target or layer._default_attn_backend\n    if target is layer.backend:\n        return\n    layer.attn_impl = layer._attn_impl_by_backend[target]\n    layer.backend = target","sourceCodeStart":283,"sourceCodeEnd":319,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/layers/attention/layer.py#L283-L319","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check layer._supported_attention_backends and request a backend that is directly supported (resolved enum == requested enum)","Update the override value to the new canonical enum name after a rename/merge in a newer sglang version","If you maintain the layer, add the desired backend to supported_attention_backends so no substitution occurs","As a workaround, remove the override and let the default backend selection apply (accepting it may not be the kernel you wanted)"],"exampleFix":"// before\nlayer._maybe_override_attention_backend(AttentionBackendEnum.OLD_ALIAS)\n// after\nassert target in layer._supported_attention_backends\nlayer._maybe_override_attention_backend(target)","handlingStrategy":"type-guard","validationCode":"if target not in layer._supported_attention_backends:\n    raise ValueError(f\"backend {target} unsupported; pick from {layer._supported_attention_backends}\")","typeGuard":"def resolves_to_self(layer, target: AttentionBackendEnum) -> bool:\n    return target in layer._supported_attention_backends","tryCatchPattern":"try:\n    layer._maybe_override_attention_backend(target)\nexcept ValueError as e:\n    if \"resolved to\" in str(e):\n        logger.warning(\"override %s not directly supported; using default backend\", target)\n    else:\n        raise","preventionTips":["Log layer._supported_attention_backends at startup to know what resolves identity-wise","After sglang upgrades, grep changelogs for backend enum renames/merges","Prefer canonical enum names over aliases in config files"],"tags":["attention","backend-override","configuration","enum-mismatch"],"backgroundTag":"config-override-resolved-to-different-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}