sgl-project/sglang · error · ValueError

num_frames/height/width must be provided for RoPE coordinate

Error message

num_frames/height/width must be provided for RoPE coordinate generation.

What it means

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.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/ltx_2.py:1991

        video_self_attention_mask: Optional[torch.Tensor] = None,
        audio_self_attention_mask: Optional[torch.Tensor] = None,
        a2v_cross_attention_mask: Optional[torch.Tensor] = None,
        v2a_cross_attention_mask: Optional[torch.Tensor] = None,
        skip_video_self_attn_blocks: Optional[tuple[int, ...]] = None,
        skip_audio_self_attn_blocks: Optional[tuple[int, ...]] = None,
        disable_a2v_cross_attn: bool = False,
        disable_v2a_cross_attn: bool = False,
        audio_replicated_for_sp: bool = False,
        video_memory_prefix_len: int = 0,
        late_layer_ratio: float = 1.0,
        late_audio_self_attention_mask: Optional[torch.Tensor] = None,
        **kwargs,
    ) -> tuple[torch.Tensor | None, torch.Tensor | None]:
        batch_size = hidden_states.size(0)
        audio_timestep = audio_timestep if audio_timestep is not None else timestep

        if num_frames is None or height is None or width is None:
            raise ValueError(
                "num_frames/height/width must be provided for RoPE coordinate generation."
            )
        if audio_num_frames is None:
            raise ValueError(
                "audio_num_frames must be provided for RoPE coordinate generation."
            )
        perturbation_configs = kwargs.get("perturbation_configs")
        if perturbation_configs is not None and len(perturbation_configs) != batch_size:
            raise ValueError(
                "perturbation_configs length must match batch size, got "
                f"{len(perturbation_configs)=} {batch_size=}."
            )

        if video_coords is None:
            # Wan-style SP-RoPE: when SP is enabled, each rank runs on its local
            # time shard but RoPE positions must be offset to global time.
            #
            # We assume equal time sharding across SP ranks.

View on GitHub (pinned to 0132848349)

Solutions

1. 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)
2. Fix the calling wrapper/scheduler to propagate video shape metadata from the request
3. Add a guard in the caller that rejects requests missing video dimensions before invoking the model

Example fix

# before
out = model(hidden_states, timestep=t)

# after
out = model(hidden_states, timestep=t,
            num_frames=latent.shape[2], height=h, width=w)

if num_frames is None or height is None or width is None:
    raise ValueError('video dims required before LTX-2 forward')
# derive from latent: num_frames=t, height=h*vae_spatial, width=w*vae_spatial

def has_video_dims(kw: dict) -> bool:
    return all(kw.get(k) is not None for k in ('num_frames','height','width'))

try: out = model(...)\nexcept ValueError as e: reject_request(str(e))  # config bug, do not retry

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• audio_num_frames must be provided for RoPE coordinate genera
• LTX-2 SP time-sharding for packed token latents currently re
• Expected {seq_len=} > 0 for packed token latents.
• Expected x.shape[-1] to be even for split rotary, got {last}
• {rope_type=} not supported. Choose between 'interleaved' and

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/a4060f7c65afb2cc. Report an issue: GitHub.