invoke-ai/InvokeAI · error · ValueError

class_labels should be provided when num_class_embeds > 0

Error message

class_labels should be provided when num_class_embeds > 0

What it means

The UNet (a diffusers UNet2DConditionModel, vendored/copied into InvokeAI's HiDiffusion module) was configured with class-label conditioning (`num_class_embeds > 0`, so `class_embedding` exists) but `forward()` was called without the `class_labels` argument. The class embedding path needs labels to project into an augmentation embedding added to the timestep embedding, so it fails fast instead of producing a misleading shape/type error later.

Source

Thrown at invokeai/backend/hidiffusion/hidiffusion.py:1057

            elif len(timesteps.shape) == 0:
                timesteps = timesteps[None].to(sample.device)

            # broadcast to batch dimension in a way that's compatible with ONNX/Core ML
            timesteps = timesteps.expand(sample.shape[0])

            t_emb = self.time_proj(timesteps)

            # `Timesteps` does not contain any weights and will always return f32 tensors
            # but time_embedding might actually be running in fp16. so we need to cast here.
            # there might be better ways to encapsulate this.
            t_emb = t_emb.to(dtype=sample.dtype)

            emb = self.time_embedding(t_emb, timestep_cond)
            aug_emb = None

            if self.class_embedding is not None:
                if class_labels is None:
                    raise ValueError("class_labels should be provided when num_class_embeds > 0")

                if self.config.class_embed_type == "timestep":
                    class_labels = self.time_proj(class_labels)

                    # `Timesteps` does not contain any weights and will always return f32 tensors
                    # there might be better ways to encapsulate this.
                    class_labels = class_labels.to(dtype=sample.dtype)

                class_emb = self.class_embedding(class_labels).to(dtype=sample.dtype)

                if self.config.class_embeddings_concat:
                    emb = torch.cat([emb, class_emb], dim=-1)
                else:
                    emb = emb + class_emb

            if self.config.addition_embed_type == "text":
                aug_emb = self.add_embedding(encoder_hidden_states)
            elif self.config.addition_embed_type == "text_image":

View on GitHub (pinned to 0b6a024f2f)

Solutions

Pass `class_labels` to the UNet call: `unet(sample, t, encoder_hidden_states, class_labels=labels)`
If class conditioning is not wanted, reload/reconfigure the UNet with `num_class_embeds=None`
Verify with `unet.config.num_class_embeds` and `unet.class_embedding is not None` before calling forward to know whether labels are required

Example fix

// before
noise_pred = unet(latent_model_input, t, encoder_hidden_states=text_emb)
// after
noise_pred = unet(latent_model_input, t, encoder_hidden_states=text_emb, class_labels=class_labels)

Defensive patterns

Strategy: validation

Validate before calling

if unet.config.num_class_embeds and class_labels is None:
    raise ValueError('This UNet requires class_labels (num_class_embeds > 0)')
noise_pred = unet(sample, t, encoder_hidden_states=emb, class_labels=class_labels)

Type guard

def needs_class_labels(unet) -> bool:
    return bool(getattr(unet.config, 'num_class_embeds', 0))

Prevention

Check `unet.config.num_class_embeds` before calling forward
Prefer running through a pipeline that supplies class_labels
When loading checkpoints, confirm whether they are class-conditioned

When it happens

Trigger: Calling `unet(sample, timestep, encoder_hidden_states)` while the model config has `num_class_embeds` set (e.g. loading a class-conditioned checkpoint like a class-conditional SD or diffusion model) and omitting `class_labels`.

Common situations: Reusing an inference pipeline written for unconditional/text-conditional models with a checkpoint that was trained class-conditioned; copying a config from a class-conditioned model into a new UNet; calling `unet.forward` directly instead of through a pipeline that supplies labels.

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

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/fb6d2d8f86030ed1. Report an issue: GitHub.