sgl-project/sglang · error · ValueError

Expected hybrid GDN or NemotronH models, but got unknown mod

Error message

Expected hybrid GDN or NemotronH models, but got unknown model. If this is a custom hybrid model, use register_linear_attn_model() from sglang.srt.configs.linear_attn_model_registry.

What it means

The hybrid-attention registry path only knows how to build a linear-attention/hybrid backend for GDN and NemotronH model families. For an unrecognized hybrid architecture it raises, pointing custom model authors at register_linear_attn_model() in sglang.srt.configs.linear_attn_model_registry.

Source

Thrown at python/sglang/srt/layers/attention/attention_registry.py:516

                linear_attn_backend = AscendKDAAttnBackend(runner)
                hybrid_backend_cls = AscendKDAHybridLinearAttnBackend
            else:
                linear_attn_backend = KDAAttnBackend(runner)
        elif hybrid_lightning_config(runner.model_config) is not None:
            linear_attn_backend = LightningAttentionBackend(runner)
        else:
            spec_result = get_linear_attn_config(runner.model_config.hf_config)
            if spec_result is not None:
                spec, _ = spec_result
                cfg = runner.model_config
                BackendClass = import_backend_class(spec.backend_class_name)
                linear_attn_backend = BackendClass(runner)
                if spec.hybrid_backend_class_name is not None:
                    hybrid_backend_cls = import_backend_class(
                        spec.hybrid_backend_class_name
                    )
            else:
                raise ValueError(
                    "Expected hybrid GDN or NemotronH models, but got unknown model. "
                    "If this is a custom hybrid model, use register_linear_attn_model() "
                    "from sglang.srt.configs.linear_attn_model_registry."
                )
        if runner.is_draft_worker:
            # FIXME: we assume that MTP/NEXTN always use full-attention.
            full_attn_layers = [0]
        else:
            full_attn_layers = cfg.full_attention_layer_ids
        return hybrid_backend_cls(
            full_attn_backend, linear_attn_backend, full_attn_layers
        )

    return full_attn_backend


@register_attention_backend("intel_xpu")
def create_intel_xpu_backend(runner):

View on GitHub (pinned to 0132848349)

Solutions

Register the model: call register_linear_attn_model() from sglang.srt.configs.linear_attn_model_registry with your architecture in model code or a plugin
Map your model onto the GDN or NemotronH config family if it is actually one of those
Check the architecture string in config.json for typos/renames

Example fix

# before
class MyHybridConfig(PretrainedConfig):
    model_type = "my_hybrid"
# after
from sglang.srt.configs.linear_attn_model_registry import register_linear_attn_model
register_linear_attn_model("my_hybrid")
class MyHybridConfig(PretrainedConfig):
    model_type = "my_hybrid"

Defensive patterns

Strategy: try-catch

Validate before calling

from sglang.srt.configs.linear_attn_model_registry import get_linear_attn_model_names
if model_type not in {"gdn-like...", *get_linear_attn_model_names()} and is_hybrid:
    raise SystemExit("register the hybrid model via register_linear_attn_model()")

Try / catch

try:
    attn_backend_wrapper(...)
except ValueError as e:
    if "register_linear_attn_model" in str(e):
        register_linear_attn_model(model_type); attn_backend_wrapper(...)  # retry once
    else:
        raise

Prevention

Register every custom hybrid architecture at import time of its config module
Fail fast in model config __init__ if the architecture is not registered

When it happens

Trigger: Loading a custom hybrid (linear-attention + full-attention) model whose architecture is neither GDN nor NemotronH (and not pre-registered) while the hybrid backend path is selected in attn_backend_wrapper.

Common situations: Adding a new hybrid model config to SGLang without registering it; renaming a model architecture so family detection fails; forked Qwen3-Next-like or custom Mamba hybrids.

Related errors

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