sgl-project/sglang · error · ValueError

audio_num_frames must be provided for RoPE coordinate genera

Error message

audio_num_frames must be provided for RoPE coordinate generation.

What it means

LTX-2's audio branch also needs RoPE coordinates, which are derived from audio_num_frames. If it is None, forward raises immediately after the video-dimension checks.

Source

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

        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.
            if model_parallel_is_initialized():
                sp_world_size = get_sp_world_size()
                sp_rank = get_sp_parallel_rank()
            else:

View on GitHub (pinned to 0132848349)

Solutions

1. Pass audio_num_frames derived from the audio latent's temporal length (e.g. audio_latent.shape[-1] or the mel-frame count per the model's audio compression)
2. Propagate audio shape metadata through the scheduler/wrapper alongside video dims
3. Guard upstream: reject requests that enable audio conditioning without audio length info

Example fix

# before
out = model(hidden_states, t, num_frames=f, height=h, width=w)

# after
out = model(hidden_states, t, num_frames=f, height=h, width=w,
            audio_num_frames=audio_latent_frames)

if audio_num_frames is None:
    audio_num_frames = audio_latent.shape[-1]  # per model audio compression
assert audio_num_frames is not None

def has_audio_dims(kw: dict) -> bool:
    return kw.get('audio_num_frames') is not None

try: out = model(...)\nexcept ValueError as e: fail_request(str(e))

When it happens

Trigger: Calling forward with video dims supplied but audio_num_frames omitted or None — e.g. an audio-capable checkpoint invoked from a pipeline that only tracks video shape.

Common situations: Audio-conditioned video generation where the wrapper computes video dims but not audio frame count; refactors dropping the audio kwargs on non-audio code paths; passing audio_timestep but forgetting audio_num_frames.

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

• num_frames/height/width must be provided for RoPE coordinate
• Expected x.shape[-1] to be even for split rotary, got {last}
• {rope_type=} not supported. Choose between 'interleaved' and
• head_dim must be a multiple of 8, got {head_dim}.
• vis_freqs_cis is required for fused QK-Norm + RoPE kernel

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