{"record":{"id":"40409c05aaa0df53","repo":"sgl-project/sglang","slug":"head-dim-must-be-positive-even-and-128","errorCode":null,"errorMessage":"head_dim must be positive, even, and <= 128","messagePattern":"head_dim must be positive, even, and <= 128","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/kernels/ops/diffusion/rope/hunyuan_qkv_pack_triton.py","lineNumber":179,"sourceCode":"    tensors = (img_q, img_k, img_v, txt_q, txt_k, txt_v)\n    if any(x.ndim != 4 for x in tensors):\n        raise ValueError(\"QKV tensors must have shape [B, S, H, D]\")\n    if any(not x.is_cuda or x.dtype != torch.bfloat16 for x in tensors):\n        raise ValueError(\"QKV tensors must be CUDA bfloat16 tensors\")\n    if any(x.device != img_q.device for x in tensors):\n        raise ValueError(\"QKV tensors must be on the same CUDA device\")\n    batch, img_tokens, num_heads, head_dim = img_q.shape\n    txt_tokens = txt_q.shape[1]\n    expected_img = (batch, img_tokens, num_heads, head_dim)\n    expected_txt = (batch, txt_tokens, num_heads, head_dim)\n    if any(tuple(x.shape) != expected_img for x in (img_q, img_k, img_v)):\n        raise ValueError(\"image QKV shapes must match\")\n    if any(tuple(x.shape) != expected_txt for x in (txt_q, txt_k, txt_v)):\n        raise ValueError(\"text QKV shapes must match\")\n    if any(x.stride(-1) != 1 for x in tensors):\n        raise ValueError(\"QKV last dimensions must be contiguous\")\n    if head_dim <= 0 or head_dim > 128 or head_dim % 2:\n        raise ValueError(\"head_dim must be positive, even, and <= 128\")\n    if cos.ndim != 2 or sin.ndim != 2 or cos.shape != sin.shape:\n        raise ValueError(\"cos and sin must have matching [S, D/2] shapes\")\n    if cos.shape[0] < img_tokens or cos.shape[1] != head_dim // 2:\n        raise ValueError(\"cos/sin shape does not cover image tokens and head_dim\")\n    if not cos.is_cuda or not sin.is_cuda or cos.stride(-1) != 1 or sin.stride(-1) != 1:\n        raise ValueError(\"cos and sin must be CUDA and last-dim contiguous\")\n    if cos.device != img_q.device or sin.device != img_q.device:\n        raise ValueError(\"QKV and cos/sin tensors must be on the same CUDA device\")\n\n    total_tokens = img_tokens + txt_tokens\n    storage = torch.empty(\n        (3, batch, total_tokens, num_heads, head_dim),\n        device=img_q.device,\n        dtype=img_q.dtype,\n    )\n    args = []\n    for x in tensors:\n        args.extend((x.stride(0), x.stride(1), x.stride(2)))","sourceCodeStart":161,"sourceCodeEnd":197,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/kernels/ops/diffusion/rope/hunyuan_qkv_pack_triton.py#L161-L197","documentation":"The Hunyuan QKV RoPE pack kernel only supports head_dim values that are positive, even, and at most 128. The even requirement comes from RoPE splitting the head into two halves, and 128 is the Triton kernel's BLOCK size limit.","triggerScenarios":"Calling hunyuan_qkv_rope_pack with head_dim inferred from an odd or >128 innermost dimension, e.g. a malformed projection layer outputting head_dim=100 or head_dim=256.","commonSituations":"Misconfigured attention head counts (num_heads*head_dim mismatch with the QKV projection width), or porting a model whose head_dim exceeds the kernel's 128 cap.","solutions":["Verify the model config's head_dim (hidden_size / num_heads) is even and <= 128.","If head_dim > 128, split the head and call the kernel per chunk or use a fallback path.","Fix the projection layer that produced the wrong head_dim."],"exampleFix":"// before\nimg_q = proj(x)  # shape [..., 100] -> head_dim=100 (odd)\nhunyuan_qkv_rope_pack(...)\n// after\nassert img_q.shape[-1] % 2 == 0 and img_q.shape[-1] <= 128, img_q.shape","handlingStrategy":"validation","validationCode":"head_dim = img_q.shape[-1]\nassert head_dim > 0 and head_dim <= 128 and head_dim % 2 == 0, head_dim","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate head_dim at model config load time.","Keep num_heads*head_dim consistent with projection width."],"tags":["rope","head-dim","shape-validation","hunyuan"],"backgroundTag":"invalid-head-dimension","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}