{"record":{"id":"e038db003b81e331","repo":"sgl-project/sglang","slug":"raw-latent-shape-must-be-t-h-w-or-b-c-t-h","errorCode":null,"errorMessage":"raw_latent_shape must be (T, H, W) or (B, C, T, H, W) for SAP attention","messagePattern":"raw_latent_shape must be \\(T, H, W\\) or \\(B, C, T, H, W\\) for SAP attention","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/layers/attention/backends/sparse_video_gen_2_attn.py","lineNumber":151,"sourceCode":"        num_k_centroids: int,\n        top_p_kmeans: float,\n        min_kc_ratio: float,\n        kmeans_iter_init: int,\n        kmeans_iter_step: int,\n        zero_step_kmeans_init: bool,\n        first_layers_fp: float,\n        first_times_fp: float,\n        context_length: int = 0,\n        prompt_length: int | None = None,\n        **kwargs: dict[str, Any],\n    ) -> SparseVideoGen2AttentionMetadata:\n        raw_shape = tuple(raw_latent_shape)\n        if len(raw_shape) == 5:\n            t, h, w = raw_shape[2:5]\n        elif len(raw_shape) == 3:\n            t, h, w = raw_shape\n        else:\n            raise ValueError(\n                \"raw_latent_shape must be (T, H, W) or (B, C, T, H, W) for SAP attention\"\n            )\n        pt, ph, pw = patch_size\n        if t % pt != 0 or h % ph != 0 or w % pw != 0:\n            raise ValueError(\n                \"raw_latent_shape must be divisible by patch_size for SAP attention\"\n            )\n\n        num_frame = t // pt\n        frame_size = (h // ph) * (w // pw)\n\n        return SparseVideoGen2AttentionMetadata(\n            current_timestep=current_timestep,\n            num_q_centroids=num_q_centroids,\n            num_k_centroids=num_k_centroids,\n            top_p_kmeans=top_p_kmeans,\n            min_kc_ratio=min_kc_ratio,\n            kmeans_iter_init=kmeans_iter_init,","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/layers/attention/backends/sparse_video_gen_2_attn.py#L133-L169","documentation":"The SVG2 attention metadata builder derives (T, H, W) from raw_latent_shape. It accepts only a 3-tuple (T, H, W) or a 5-tuple (B, C, T, H, W); any other rank (e.g. 4-tuple (C, T, H, W)) raises this ValueError.","triggerScenarios":"Passing raw_latent_shape with 4 elements (channel-first without batch, a common VAE-latent convention) or a flattened scalar/6-tuple; e.g. raw_latent_shape=(16, 64, 64) is fine but (16, 64, 64, 64) fails.","commonSituations":"Adapting latent shapes from a diffusion VAE whose latents are (C,T,H,W); passing a torch.Size directly where dims don't line up; misreading whether B and C should be included.","solutions":["Pass a 3-tuple (T, H, W) of spatial-temporal dims only, or a full 5-tuple (B, C, T, H, W).","If you have a (C,T,H,W) latent, strip the channel dim: raw_latent_shape = tuple(latent.shape[1:]) (giving (T,H,W)).","Double-check against the builder's expectations: it reads raw_shape[2:5] for 5-tuples, so ordering matters (B, C, then T, H, W)."],"exampleFix":"# before\nbuilder.build(kwargs={\"raw_latent_shape\": (C, T, H, W), ...})  # 4-tuple -> ValueError\n\n# after\nbuilder.build(kwargs={\"raw_latent_shape\": (T, H, W), ...})  # or (B, C, T, H, W)","handlingStrategy":"validation","validationCode":"def norm_latent_shape(s):\n    s = tuple(s)\n    if len(s) == 5:\n        return s[2:5]\n    if len(s) == 3:\n        return s\n    raise ValueError(f\"bad raw_latent_shape: {s}\")\n\nT, H, W = norm_latent_shape(latent.shape)  # validate before build","typeGuard":"def is_valid_latent_shape(s) -> bool:\n    return len(tuple(s)) in (3, 5)","tryCatchPattern":null,"preventionTips":["Always derive raw_latent_shape from the actual latent tensor's .shape, not hand-typed tuples.","Remember (B, C, T, H, W) ordering for 5-tuples; T is index 2.","Wrap shape normalization in a helper shared across layers."],"tags":["shape-validation","latent-shape","video-generation"],"backgroundTag":"invalid-tensor-shape","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}