sgl-project/sglang · error · ValueError

Unknown history_scale_mode: {history_scale_mode}

Error message

Unknown history_scale_mode: {history_scale_mode}

What it means

In the Helios DiT attention module, when is_amplify_history is enabled the history key scaling mode must be 'scalar' (single learnable scale) or 'per_head' (one scale per head). Any other history_scale_mode string raises this ValueError in __init__.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/helios.py:284

        self.norm_q = RMSNorm(dim, eps=eps)
        self.norm_k = RMSNorm(dim, eps=eps)
        self.tp_rmsnorm = tp_size > 1

        self.attn = USPAttention(
            num_heads=self.local_num_heads,
            head_size=self.head_dim,
            causal=False,
            is_cross_attention=False,
        )

        self.is_amplify_history = is_amplify_history
        if is_amplify_history:
            if history_scale_mode == "scalar":
                self.history_key_scale = nn.Parameter(torch.ones(1))
            elif history_scale_mode == "per_head":
                self.history_key_scale = nn.Parameter(torch.ones(num_heads))
            else:
                raise ValueError(f"Unknown history_scale_mode: {history_scale_mode}")
            self.history_scale_mode = history_scale_mode
            self.max_scale = 10.0

    def forward(self, hidden_states, rotary_emb=None, original_context_length=None):
        q, _ = self.to_q(hidden_states)
        k, _ = self.to_k(hidden_states)
        v, _ = self.to_v(hidden_states)

        if self.tp_rmsnorm:
            q = tensor_parallel_rms_norm(q, self.norm_q)
            k = tensor_parallel_rms_norm(k, self.norm_k)
        else:
            q = self.norm_q(q)
            k = self.norm_k(k)

        q = q.unflatten(2, (self.local_num_heads, self.head_dim))
        k = k.unflatten(2, (self.local_num_heads, self.head_dim))
        v = v.unflatten(2, (self.local_num_heads, self.head_dim))

View on GitHub (pinned to 0132848349)

Solutions

1. Use history_scale_mode='scalar' or 'per_head' when is_amplify_history is True
2. If you don't need history amplification, set is_amplify_history=False so history_scale_mode is ignored
3. Check the Helios config shipped with the pretrained checkpoint for the trained mode value

Example fix

# before
attn = HeliosAttention(..., is_amplify_history=True, history_scale_mode="vector")

# after
attn = HeliosAttention(..., is_amplify_history=True, history_scale_mode="per_head")

if is_amplify_history:
    assert history_scale_mode in ('scalar', 'per_head'), history_scale_mode

def is_valid_history_scale_mode(v: str) -> bool:
    return v in ('scalar', 'per_head')

When it happens

Trigger: Constructing Helios attention with is_amplify_history=True and history_scale_mode set to something other than 'scalar' or 'per_head' (e.g. 'per-channel', 'vector', or an unset placeholder string).

Common situations: Enabling the history-amplification feature experimentally with a guessed mode name; configs carried over from a fork that renamed the modes.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Invalid threshold_type for topk: {threshold_type}. Choose 'q
• Invalid threshold_type: {threshold_type}. Choose 'query_head
• unknown qk_norm: {qk_norm}. Should be one of None, 'layer_no
• unknown norm_type {norm_type}
• Hidden size {hidden_size} must be divisible by num_heads {nu

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