sgl-project/sglang · error · ValueError

SANA-WM refiner expects 5D latents shaped (B, C, T, H, W), g

Error message

SANA-WM refiner expects 5D latents shaped (B, C, T, H, W), got {tuple(batch.latents.shape)}.

What it means

forward() validates that batch.latents.ndim == 5, i.e. shaped (B, C, T, H, W) as produced by SANA-WM video generation. A 4D image-style latent or any other rank is rejected with the actual shape echoed in the message.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/sana_wm/refiner.py:713

                patch_size=patch_size,
                patch_size_t=patch_size_t,
            )
            log_sana_wm_tensor_stats(
                f"refiner.step_{step_idx}.velocity_current",
                velocity_5d.to(self.dtype),
            )
            log_sana_wm_tensor_stats(f"refiner.step_{step_idx}.current_latent", noisy)

        refined = torch.cat([sink, noisy], dim=2)
        log_sana_wm_tensor_stats("refiner.output_latent", refined)
        return refined

    @torch.inference_mode()
    def forward(self, batch: Req, server_args: ServerArgs) -> Req:
        if batch.latents is None:
            raise ValueError("SANA-WM refiner requires batch.latents from stage 1.")
        if batch.latents.ndim != 5:
            raise ValueError(
                "SANA-WM refiner expects 5D latents shaped (B, C, T, H, W), "
                f"got {tuple(batch.latents.shape)}."
            )

        if sana_wm_skip_refiner_enabled(batch):
            if batch.extra is None:
                batch.extra = {}
            batch.extra["sana_wm_refiner_applied"] = False
            self.log_info(
                "SANA-WM LTX-2 refiner skipped by SGLANG_SANA_WM_SKIP_REFINER."
            )
            return batch

        batch_size = int(batch.latents.shape[0])
        prompts = self._prompts_for_batch(batch, batch_size)
        fps = float(getattr(batch, "fps", 16) or 16)

        seeds: list[int]

View on GitHub (pinned to 0132848349)

Solutions

Keep latents 5D: unsqueeze dim 2 if the temporal axis was squeezed
Check the producing stage emits (B, C, T, H, W) video latents
If refining images, use the image-specific stage, not the SANA-WM video refiner

Example fix

# before
batch.latents = z_4d  # (B, C, H, W)
# after
batch.latents = z_4d.unsqueeze(2)  # (B, C, 1, H, W) -- note also sink_size constraint

Defensive patterns

Strategy: type-guard

Validate before calling

assert batch.latents is not None and batch.latents.ndim == 5, tuple(batch.latents.shape if batch.latents is not None else ())

Type guard

def is_5d_latents(z) -> bool:
    return isinstance(z, torch.Tensor) and z.ndim == 5

Try / catch

try:
    out = refiner.forward(batch, server_args)
except ValueError as e:
    if "5D latents" in str(e) and batch.latents.ndim == 4:
        batch.latents = batch.latents.unsqueeze(2)
        out = refiner.forward(batch, server_args)
    else:
        raise

Prevention

Standardize on (B, C, T, H, W) across all video stages
Avoid squeezing singleton temporal dims in transport code
Add shape assertions in stage unit tests

When it happens

Trigger: Passing an image-pipeline latent (B, C, H, W) or an unsqueezed/packed tensor of the wrong rank into the video refiner; a stage that squeezes the temporal dimension (single-frame output) before the refiner.

Common situations: Reusing the refiner from an image pipeline; a preprocessing stage collapsing T=1 latents to 4D; latents stored/transferred through a path that drops a singleton dim.

Related errors

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