sgl-project/sglang · error · ValueError

Hunyuan3D Paint expects square latents and a matching view c

Error message

Hunyuan3D Paint expects square latents and a matching view count.

What it means

The paint UNet requires square spatial latents (height == width) and that sample.shape[1] (num_generated views) equals the num_in_batch the model/pipeline was configured with, because multiview/reference attention rearranges '(b n) l c' tensors using that count. A mismatch raises this ValueError early in forward.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/hunyuan3d_paint.py:330

        normal_imgs: torch.Tensor | None = None,
        position_imgs: torch.Tensor | None = None,
        camera_info_gen: torch.Tensor,
        camera_info_ref: torch.Tensor,
        ref_scale: float | torch.Tensor = 1.0,
        mva_scale: float | torch.Tensor = 1.0,
        position_attn_mask: dict[int, torch.Tensor] | None = None,
        timestep_cond: torch.Tensor | None = None,
        cross_attention_kwargs: dict[str, Any] | None = None,
        added_cond_kwargs: dict[str, torch.Tensor] | None = None,
        return_dict: bool = True,
    ) -> StableDiffusionUNetOutput | tuple[torch.Tensor]:
        if timestep_cond is not None or cross_attention_kwargs is not None:
            raise ValueError("Hunyuan3D Paint does not use extra UNet conditioning.")
        if added_cond_kwargs is not None:
            raise ValueError("Hunyuan3D Paint does not use added conditioning.")
        batch_size, num_generated, _, height, width = sample.shape
        if height != width or num_generated != num_in_batch:
            raise ValueError(
                "Hunyuan3D Paint expects square latents and a matching view count."
            )

        camera_gen = rearrange(
            camera_info_gen + self.max_num_ref_images, "b n -> (b n)"
        )
        inputs = [sample]
        if normal_imgs is not None:
            inputs.append(normal_imgs)
        if position_imgs is not None:
            inputs.append(position_imgs)
        sample = rearrange(torch.cat(inputs, dim=2), "b n c h w -> (b n) c h w")
        encoder_gen = encoder_hidden_states.unsqueeze(1).repeat(1, num_generated, 1, 1)
        encoder_gen = rearrange(encoder_gen, "b n l c -> (b n) l c")

        if not condition_embed_dict:
            num_reference = ref_latents.shape[1]
            camera_ref = rearrange(camera_info_ref, "b n -> (b n)")

View on GitHub (pinned to 0132848349)

Solutions

1. Make the latent height equal to width (square generation)
2. Ensure sample's view count equals num_in_batch (both the tensor layout and the pipeline setting)
3. Regenerate latents with the pipeline's own prepare_latents so shapes stay consistent

Example fix

# before
sample = torch.randn(b, 6, 4, 64, 48)  # 6 views, num_in_batch=4, non-square

# after
sample = torch.randn(b, 4, 4, 64, 64)  # 4 views, square latents

b, n, _, h, w = sample.shape
assert h == w and n == num_in_batch, f'{h}x{w} with {n} views vs num_in_batch={num_in_batch}'

def latents_valid(sample: torch.Tensor, num_in_batch: int) -> bool:
    _, n, _, h, w = sample.shape
    return h == w and n == num_in_batch

When it happens

Trigger: Passing non-square latents (e.g. 64x48) or a sample whose view dimension differs from num_in_batch (e.g. batch of 6 views while num_in_batch=4).

Common situations: Generating a non-square canvas; changing the number of generated views without updating the pipeline's num_in_batch; reshaping latents incorrectly before the denoising loop.

Related errors

• Multiview attention was not initialized.
• vis_freqs_cis must be a 2D cos_sin_cache tensor
• {debug_name}: current-chunk rewrite size changed
• encoder_hidden_states is required when encoder_key_value is
• Didn't get guidance strength for guidance distilled model.

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