{"record":{"id":"72032d7005989d9f","repo":"sgl-project/sglang","slug":"vis-freqs-cis-must-be-a-2d-cos-sin-cache-tensor","errorCode":null,"errorMessage":"vis_freqs_cis must be a 2D cos_sin_cache tensor","messagePattern":"vis_freqs_cis must be a 2D cos_sin_cache tensor","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/joy_image.py","lineNumber":257,"sourceCode":"            txt_mod2_scale,\n            txt_mod2_gate,\n        ) = self.txt_mod(vec)\n\n        # Image attention\n        img_modulated = self.fused_modulate_img_norm1(\n            img, shift=img_mod1_shift, scale=img_mod1_scale\n        )\n        img_qkv, _ = self.img_attn_qkv(img_modulated)\n        img_q, img_k, img_v = rearrange(\n            img_qkv, \"B L (K H D) -> K B L H D\", K=3, H=self.local_heads_num\n        )\n\n        if vis_freqs_cis is None:\n            raise ValueError(\n                \"vis_freqs_cis is required for fused QK-Norm + RoPE kernel\"\n            )\n        if not (isinstance(vis_freqs_cis, torch.Tensor) and vis_freqs_cis.dim() == 2):\n            raise ValueError(\"vis_freqs_cis must be a 2D cos_sin_cache tensor\")\n        if img_q.dtype not in (torch.float16, torch.bfloat16):\n            raise ValueError(\n                f\"Fused QK-Norm + RoPE kernel only supports float16/bfloat16, but got {img_q.dtype}\"\n            )\n        img_q = img_q.contiguous()\n        img_k = img_k.contiguous()\n        img_q, img_k = apply_qk_norm_with_optional_rope(\n            q=img_q,\n            k=img_k,\n            q_norm=self.img_attn_q_norm,\n            k_norm=self.img_attn_k_norm,\n            head_dim=img_q.shape[-1],\n            cos_sin_cache=vis_freqs_cis,\n            is_neox=False,\n            allow_inplace=True,\n        )\n        img_q, img_k = img_q.to(img_v), img_k.to(img_v)\n","sourceCodeStart":239,"sourceCodeEnd":275,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/joy_image.py#L239-L275","documentation":"The fused QK-Norm + RoPE kernel in joy_image takes the rotary cache as a 2D (cos_sin) tensor. If vis_freqs_cis is not a torch.Tensor or does not have exactly 2 dimensions (e.g. a 3D complex cache or a tuple), this ValueError is raised.","triggerScenarios":"Passing a freqs_cis in complex/tensor-of-pairs format (3D: [seq, heads, dim]) or a non-tensor (tuple of (cos, sin)) instead of the expected 2D [seq, cos_sin_dim] layout.","commonSituations":"Reusing a rope cache builder from another model (e.g. flux-style complex freqs) that returns a different shape; passing torch.stack([cos, sin]) without flattening.","solutions":["Convert the cache to a 2D tensor: cat cos and sin along the feature dim to get [seq, head_dim]","Ensure you pass a torch.Tensor, not a tuple or list","Build the cache with the model's own rotary-embedding helper that emits the cos_sin 2D layout"],"exampleFix":"# before\nvis_freqs_cis = torch.view_as_complex(freqs_3d)  # or a (cos, sin) tuple\n\n# after\nvis_freqs_cis = torch.cat([cos, sin], dim=-1)  # shape [seq, head_dim], 2D","handlingStrategy":"type-guard","validationCode":"assert isinstance(vis_freqs_cis, torch.Tensor) and vis_freqs_cis.dim() == 2, vis_freqs_cis.shape if isinstance(vis_freqs_cis, torch.Tensor) else type(vis_freqs_cis)","typeGuard":"def is_2d_cos_sin_cache(x) -> bool:\n    return isinstance(x, torch.Tensor) and x.dim() == 2","tryCatchPattern":null,"preventionTips":["Standardize on the 2D [seq, head_dim] cos_sin layout for rope caches","Use the model's own rotary helper to build caches rather than external builders"],"tags":["runtime","rope","shape-mismatch","diffusion"],"backgroundTag":"tensor-shape-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}