{"record":{"id":"a4060f7c65afb2cc","repo":"sgl-project/sglang","slug":"num-frames-height-width-must-be-provided-for-rope","errorCode":null,"errorMessage":"num_frames/height/width must be provided for RoPE coordinate generation.","messagePattern":"num_frames/height/width must be provided for RoPE coordinate generation\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/ltx_2.py","lineNumber":1991,"sourceCode":"        video_self_attention_mask: Optional[torch.Tensor] = None,\n        audio_self_attention_mask: Optional[torch.Tensor] = None,\n        a2v_cross_attention_mask: Optional[torch.Tensor] = None,\n        v2a_cross_attention_mask: Optional[torch.Tensor] = None,\n        skip_video_self_attn_blocks: Optional[tuple[int, ...]] = None,\n        skip_audio_self_attn_blocks: Optional[tuple[int, ...]] = None,\n        disable_a2v_cross_attn: bool = False,\n        disable_v2a_cross_attn: bool = False,\n        audio_replicated_for_sp: bool = False,\n        video_memory_prefix_len: int = 0,\n        late_layer_ratio: float = 1.0,\n        late_audio_self_attention_mask: Optional[torch.Tensor] = None,\n        **kwargs,\n    ) -> tuple[torch.Tensor | None, torch.Tensor | None]:\n        batch_size = hidden_states.size(0)\n        audio_timestep = audio_timestep if audio_timestep is not None else timestep\n\n        if num_frames is None or height is None or width is None:\n            raise ValueError(\n                \"num_frames/height/width must be provided for RoPE coordinate generation.\"\n            )\n        if audio_num_frames is None:\n            raise ValueError(\n                \"audio_num_frames must be provided for RoPE coordinate generation.\"\n            )\n        perturbation_configs = kwargs.get(\"perturbation_configs\")\n        if perturbation_configs is not None and len(perturbation_configs) != batch_size:\n            raise ValueError(\n                \"perturbation_configs length must match batch size, got \"\n                f\"{len(perturbation_configs)=} {batch_size=}.\"\n            )\n\n        if video_coords is None:\n            # Wan-style SP-RoPE: when SP is enabled, each rank runs on its local\n            # time shard but RoPE positions must be offset to global time.\n            #\n            # We assume equal time sharding across SP ranks.","sourceCodeStart":1973,"sourceCodeEnd":2009,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/ltx_2.py#L1973-L2009","documentation":"The LTX-2 forward pass needs explicit video spatial/temporal dimensions (num_frames, height, width) to generate RoPE position coordinates, since unlike LLM decoders there is no cached position_ids. If any of the three is None, forward refuses to run.","triggerScenarios":"Calling model.forward(hidden_states, timestep, ...) without passing num_frames/height/width kwargs, or passing them as None (e.g. defaults in a wrapper that were never populated from the request metadata).","commonSituations":"Building a custom generation pipeline that omits video shape metadata; refactors where the scheduler stops forwarding the video-shape kwargs; text-only or audio-only code paths accidentally reaching the video forward.","solutions":["Pass num_frames, height, width explicitly to forward, derived from the input video latent shape (e.g. latent [B,C,T,H,W] -> num_frames=T, height=H*8, width=W*8 for typical VAE spatial compression)","Fix the calling wrapper/scheduler to propagate video shape metadata from the request","Add a guard in the caller that rejects requests missing video dimensions before invoking the model"],"exampleFix":"# before\nout = model(hidden_states, timestep=t)\n\n# after\nout = model(hidden_states, timestep=t,\n            num_frames=latent.shape[2], height=h, width=w)","handlingStrategy":"validation","validationCode":"if num_frames is None or height is None or width is None:\n    raise ValueError('video dims required before LTX-2 forward')\n# derive from latent: num_frames=t, height=h*vae_spatial, width=w*vae_spatial","typeGuard":"def has_video_dims(kw: dict) -> bool:\n    return all(kw.get(k) is not None for k in ('num_frames','height','width'))","tryCatchPattern":"try: out = model(...)\\nexcept ValueError as e: reject_request(str(e))  # config bug, do not retry","preventionTips":["Populate shape metadata at request admission","Never default video dims to None in wrappers that reach forward"],"tags":["rope","missing-argument","ltx-2","forward","video"],"backgroundTag":"missing-required-argument","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}