{"record":{"id":"189dede843078aeb","repo":"sgl-project/sglang","slug":"sol-attn-requires-head-size-sol-attn-head-dim","errorCode":null,"errorMessage":"Sol-Attn requires head_size={_SOL_ATTN_HEAD_DIM}, got {head_size}","messagePattern":"Sol-Attn requires head_size=(.+?), got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/layers/attention/backends/sol_attn.py","lineNumber":115,"sourceCode":"    def get_impl_cls() -> type[SolAttnImpl]:\n        return SolAttnImpl\n\n\nclass SolAttnImpl(AttentionImpl):\n\n    def __init__(\n        self,\n        num_heads: int,\n        head_size: int,\n        causal: bool,\n        softmax_scale: float,\n        num_kv_heads: int | None = None,\n        prefix: str = \"\",\n        **extra_impl_args,\n    ) -> None:\n        del num_heads, num_kv_heads, extra_impl_args\n        if head_size != _SOL_ATTN_HEAD_DIM:\n            raise ValueError(\n                f\"Sol-Attn requires head_size={_SOL_ATTN_HEAD_DIM}, got {head_size}\"\n            )\n        self.causal = causal\n        self.softmax_scale = softmax_scale\n        self.prefix = prefix\n        self.layer_idx = self._parse_layer_idx(prefix)\n        self._sol_params: frozenset[str] | None = None\n\n    @staticmethod\n    def _parse_layer_idx(prefix: str) -> int | None:\n        match = re.search(r\"blocks\\.(\\d+)\", prefix)\n        return int(match.group(1)) if match else None\n\n    def _should_use_dense(self) -> bool:\n        cfg = _get_sol_attn_runtime_config()\n        try:\n            from sglang.multimodal_gen.runtime.managers.forward_context import (\n                get_forward_context,","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/layers/attention/backends/sol_attn.py#L97-L133","documentation":"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.","triggerScenarios":"Constructing the Sol-Attn attention implementation with head_size != _SOL_ATTN_HEAD_DIM (check the constant in sol_attn.py).","commonSituations":"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.","solutions":["Check _SOL_ATTN_HEAD_DIM in sol_attn.py and use sol_attn only for models with that head size","Switch to a backend supporting arbitrary head dims (flash_attn)","If you control the kernel, add support for the needed head dim upstream"],"exampleFix":"# before\nimpl = SolAttnImpl(head_size=64, ...)  # raises if _SOL_ATTN_HEAD_DIM == 128\n# after\nimpl = FlashAttentionImpl(head_size=64, ...)","handlingStrategy":"validation","validationCode":"from sglang.multimodal_gen.runtime.layers.attention.backends.sol_attn import _SOL_ATTN_HEAD_DIM\nassert head_size == _SOL_ATTN_HEAD_DIM, f\"sol_attn needs head_size={_SOL_ATTN_HEAD_DIM}\"","typeGuard":"def sol_attn_compatible(head_size: int) -> bool:\n    from sglang.multimodal_gen.runtime.layers.attention.backends.sol_attn import _SOL_ATTN_HEAD_DIM\n    return head_size == _SOL_ATTN_HEAD_DIM","tryCatchPattern":null,"preventionTips":["Gate backend selection on model head dim","Keep a backend capability table (supported head dims) and consult it at startup"],"tags":["sol-attn","head-size","unsupported-dimension","init"],"backgroundTag":"unsupported-tensor-dimension","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}