sgl-project/sglang · error · ValueError

class_labels are required by this UNet.

Error message

class_labels are required by this UNet.

What it means

Raised by the Hunyuan3D SD2.1 UNet forward when the config created a class_embedding but the caller passed class_labels=None. Classifier-free guidance setups on class-conditional checkpoints still need dummy labels when the embedding exists.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/stable_diffusion.py:847

            raise ValueError("T2I adapter residuals are not supported by Hunyuan3D.")
        if (down_block_additional_residuals is None) != (
            mid_block_additional_residual is None
        ):
            raise ValueError(
                "ControlNet down and mid residuals must be provided together."
            )

        attention_mask = self._attention_bias(attention_mask, sample.dtype)
        encoder_attention_mask = self._attention_bias(
            encoder_attention_mask, sample.dtype
        )
        if self.config.center_input_sample:
            sample = 2 * sample - 1.0

        time_embedding = self._time_embedding(sample, timestep)
        if self.class_embedding is not None:
            if class_labels is None:
                raise ValueError("class_labels are required by this UNet.")
            time_embedding = time_embedding + self.class_embedding(class_labels).to(
                sample.dtype
            )

        forward_upsample_size = any(
            dimension % 8 != 0 for dimension in sample.shape[-2:]
        )
        sample = self.conv_in(sample)
        down_residuals = (sample,)
        for block in self.down_blocks:
            if isinstance(block, CrossAttnDownBlock2D):
                sample, residuals = block(
                    sample,
                    time_embedding,
                    encoder_hidden_states,
                    attention_mask,
                    encoder_attention_mask,
                    cross_attention_kwargs,

View on GitHub (pinned to 0132848349)

Solutions

1. Pass class_labels of shape [B] (or [B, embedding_dim]) to forward
2. If class conditioning is unwanted, load the config with num_class_embeds unset/0 so class_embedding is None
3. Use zero/dummy labels matching batch size for unconditional pass

Example fix

# before
out = unet(x, t, encoder_hidden_states=ctx)
# after
labels = torch.zeros(x.shape[0], dtype=torch.long, device=x.device)
out = unet(x, t, encoder_hidden_states=ctx, class_labels=labels)

if unet.class_embedding is not None and class_labels is None:
    class_labels = torch.zeros(sample.shape[0], dtype=torch.long, device=sample.device)

def needs_class_labels(unet) -> bool:
    return unet.class_embedding is not None

When it happens

Trigger: Instantiating the UNet with num_class_embeds > 0 (creating class_embedding) then calling forward without class_labels.

Common situations: Loading a class-conditional SD2 checkpoint and running plain CFG sampling with no class labels provided.

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

• Usage: sglang serve --model-path <model-name-or-path> [addit
• Error: --model-path is required. Please provide the path to
• v_cache must be provided
• q must be provided unless qv is provided with only_qv=True
• mask_block_cnt and mask_block_idx must be provided for block

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