sgl-project/sglang · error · ValueError

num_frames/height/width are required when hidden_states is p

Error message

num_frames/height/width are required when hidden_states is pre-packed.

What it means

The refiner transformer can both pack raw latents itself and accept pre-packed token sequences. If hidden_states is already packed (token form), you must tell it the original video geometry via num_frames/height/width so RoPE and attention windows can be computed.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/sana_wm_refiner_transformer.py:358

    ) -> torch.Tensor:
        # Accept either packed (B, L, in_dim) or raw 5D (B, C, T, H, W).
        if hidden_states.dim() == 5:
            B_, _, T_, H_, W_ = hidden_states.shape
            if num_frames is None:
                num_frames = T_
            if height is None:
                height = H_
            if width is None:
                width = W_
            hidden_states = pack_latents(
                hidden_states,
                patch_size=self.patch_size,
                patch_size_t=self.patch_size_t,
            )
            packed_input = True
        else:
            if num_frames is None or height is None or width is None:
                raise ValueError(
                    "num_frames/height/width are required when hidden_states is pre-packed."
                )
            packed_input = False

        B = hidden_states.size(0)

        video_coords = self.rope.prepare_video_coords(
            batch_size=B,
            num_frames=num_frames,
            height=height,
            width=width,
            device=hidden_states.device,
            fps=fps,
        )
        video_rotary_emb = self.rope(
            video_coords,
            device=hidden_states.device,
            out_dtype=hidden_states.dtype,

View on GitHub (pinned to 0132848349)

Solutions

1. Pass num_frames, height, and width (the latent-plane dimensions) alongside packed hidden_states
2. Or pass unpacked 5-D hidden_states (B, C, T, H, W) and let the refiner pack internally
3. Store geometry alongside cached packed latents so it is never lost

Example fix

# before
out = refiner(packed_h, timestep=t, encoder_hidden_states=ehs)
# after
out = refiner(packed_h, timestep=t, encoder_hidden_states=ehs,
              num_frames=T, height=H, width=W)

if hidden_states.ndim == 3:
    assert num_frames and height and width, 'geometry required for packed input'

def is_unpacked(h: torch.Tensor) -> bool: return h.ndim == 5

When it happens

Trigger: Calling forward with 3-D pre-packed hidden_states (B, tokens, C) but omitting any of num_frames, height, width.

Common situations: Caching packed latents from a previous stage and forwarding without geometry metadata; porting a pipeline that assumed the model infers geometry (it can't from packed tokens alone).

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

• SANA-WM forward requires encoder_hidden_states.
• SANA-WM forward requires timestep.
• SANA-WM forward_long requires encoder_hidden_states.
• SANA-WM forward_long requires timestep.
• Either chunk_index or chunk_size must be provided.

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