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 patched UNet2DConditionModel.forward requires class_labels whenever the model has a class_embedding (i.e. num_class_embeds > 0), because class conditioning must be embedded and added to the timestep embedding. Calling forward without them makes class conditioning impossible, so it fails fast.

Source

Thrown at invokeai/backend/util/hotfixes.py:673

        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)

            class_emb = self.class_embedding(class_labels).to(dtype=self.dtype)
            emb = emb + class_emb

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

            elif self.config.addition_embed_type == "text_time":
                if "text_embeds" not in added_cond_kwargs:
                    raise ValueError(
                        f"{self.__class__} has the config param `addition_embed_type` set to 'text_time' which \
                            requires the keyword argument `text_embeds` to be passed in `added_cond_kwargs`"
                    )
                text_embeds = added_cond_kwargs.get("text_embeds")

View on GitHub (pinned to 0b6a024f2f)

Solutions

Pass class_labels (tensor of per-sample class ids) to forward()
If class conditioning is unwanted, use a checkpoint/config with num_class_embeds = 0
Add the labels to added_cond_kwargs/class kwargs if going through a pipeline that expects them there

Example fix

// before
unet(sample, timestep, encoder_hidden_states)
// after
unet(sample, timestep, encoder_hidden_states, class_labels=torch.tensor([0], device=sample.device))

Defensive patterns

Strategy: validation

Validate before calling

needs_labels = getattr(unet.config, 'num_class_embeds', 0) > 0
if needs_labels and class_labels is None:
    raise ValueError("this UNet requires class_labels")

Type guard

def class_conditioning_ok(unet, class_labels):
    return getattr(unet.config, 'num_class_embeds', 0) == 0 or class_labels is not None

Try / catch

try:
    noise_pred = unet(sample, t, encoder_hidden_states, class_labels=class_labels)
except ValueError as e:
    logger.error("class conditioning mismatch: %s", e)
    raise

Prevention

Check num_class_embeds in the checkpoint config before building the loop
Thread class_labels through the whole sampling loop, not just step one
Prefer official pipelines for class-conditioned models

When it happens

Trigger: Calling forward() on a UNet configured with num_class_embeds > 0 (e.g. class_embed_type 'timestep' or 'identity') without passing class_labels; using a generic sampling loop that never supplies class labels against a class-conditioned checkpoint.

Common situations: Swapping in a class-conditioned model (e.g. class-free UNet variants, some SD fine-tunes) into code written for plain SD; forgetting class labels in custom denoising loops.

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/c89e49fa11d2cd9f. Report an issue: GitHub.