sgl-project/sglang · error · ValueError

Sol-Attn requires head_size={_SOL_ATTN_HEAD_DIM}, got {head_

Error message

Sol-Attn requires head_size={_SOL_ATTN_HEAD_DIM}, got {head_size}

What it means

Sol-Attn kernels support only a single fixed head dimension (_SOL_ATTN_HEAD_DIM); __init__ deletes the head-count args and hard-checks head_size. Constructing the backend for a model with a different per-head dimension raises ValueError immediately.

Source

Thrown at python/sglang/multimodal_gen/runtime/layers/attention/backends/sol_attn.py:115

    def get_impl_cls() -> type[SolAttnImpl]:
        return SolAttnImpl


class SolAttnImpl(AttentionImpl):

    def __init__(
        self,
        num_heads: int,
        head_size: int,
        causal: bool,
        softmax_scale: float,
        num_kv_heads: int | None = None,
        prefix: str = "",
        **extra_impl_args,
    ) -> None:
        del num_heads, num_kv_heads, extra_impl_args
        if head_size != _SOL_ATTN_HEAD_DIM:
            raise ValueError(
                f"Sol-Attn requires head_size={_SOL_ATTN_HEAD_DIM}, got {head_size}"
            )
        self.causal = causal
        self.softmax_scale = softmax_scale
        self.prefix = prefix
        self.layer_idx = self._parse_layer_idx(prefix)
        self._sol_params: frozenset[str] | None = None

    @staticmethod
    def _parse_layer_idx(prefix: str) -> int | None:
        match = re.search(r"blocks\.(\d+)", prefix)
        return int(match.group(1)) if match else None

    def _should_use_dense(self) -> bool:
        cfg = _get_sol_attn_runtime_config()
        try:
            from sglang.multimodal_gen.runtime.managers.forward_context import (
                get_forward_context,

View on GitHub (pinned to 0132848349)

Solutions

1. Check _SOL_ATTN_HEAD_DIM in sol_attn.py and use sol_attn only for models with that head size
2. Switch to a backend supporting arbitrary head dims (flash_attn)
3. If you control the kernel, add support for the needed head dim upstream

Example fix

# before
impl = SolAttnImpl(head_size=64, ...)  # raises if _SOL_ATTN_HEAD_DIM == 128
# after
impl = FlashAttentionImpl(head_size=64, ...)

from sglang.multimodal_gen.runtime.layers.attention.backends.sol_attn import _SOL_ATTN_HEAD_DIM
assert head_size == _SOL_ATTN_HEAD_DIM, f"sol_attn needs head_size={_SOL_ATTN_HEAD_DIM}"

def sol_attn_compatible(head_size: int) -> bool:
    from sglang.multimodal_gen.runtime.layers.attention.backends.sol_attn import _SOL_ATTN_HEAD_DIM
    return head_size == _SOL_ATTN_HEAD_DIM

When it happens

Trigger: Constructing the Sol-Attn attention implementation with head_size != _SOL_ATTN_HEAD_DIM (check the constant in sol_attn.py).

Common situations: Pointing sol_attn at a model with 64-dim heads when the kernel requires another size; new model variants; mismatch between model config and sol-attn kernel constraints.

Related errors

• st attn not supported
• SGLANG_DIFFUSION_ATTENTION_CONFIG is not set
• Unsupported sol_attn dense_backend={dense_backend!r}; expect
• TP size must be positive.
• QK Norm type not supported

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