{"record":{"id":"fb6d2d8f86030ed1","repo":"invoke-ai/InvokeAI","slug":"class-labels-should-be-provided-when-num-class-emb","errorCode":null,"errorMessage":"class_labels should be provided when num_class_embeds > 0","messagePattern":"class_labels should be provided when num_class_embeds > 0","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/hidiffusion/hidiffusion.py","lineNumber":1057,"sourceCode":"            elif len(timesteps.shape) == 0:\n                timesteps = timesteps[None].to(sample.device)\n\n            # broadcast to batch dimension in a way that's compatible with ONNX/Core ML\n            timesteps = timesteps.expand(sample.shape[0])\n\n            t_emb = self.time_proj(timesteps)\n\n            # `Timesteps` does not contain any weights and will always return f32 tensors\n            # but time_embedding might actually be running in fp16. so we need to cast here.\n            # there might be better ways to encapsulate this.\n            t_emb = t_emb.to(dtype=sample.dtype)\n\n            emb = self.time_embedding(t_emb, timestep_cond)\n            aug_emb = None\n\n            if self.class_embedding is not None:\n                if class_labels is None:\n                    raise ValueError(\"class_labels should be provided when num_class_embeds > 0\")\n\n                if self.config.class_embed_type == \"timestep\":\n                    class_labels = self.time_proj(class_labels)\n\n                    # `Timesteps` does not contain any weights and will always return f32 tensors\n                    # there might be better ways to encapsulate this.\n                    class_labels = class_labels.to(dtype=sample.dtype)\n\n                class_emb = self.class_embedding(class_labels).to(dtype=sample.dtype)\n\n                if self.config.class_embeddings_concat:\n                    emb = torch.cat([emb, class_emb], dim=-1)\n                else:\n                    emb = emb + class_emb\n\n            if self.config.addition_embed_type == \"text\":\n                aug_emb = self.add_embedding(encoder_hidden_states)\n            elif self.config.addition_embed_type == \"text_image\":","sourceCodeStart":1039,"sourceCodeEnd":1075,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/hidiffusion/hidiffusion.py#L1039-L1075","documentation":"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.","triggerScenarios":"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`.","commonSituations":"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.","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"],"exampleFix":"// before\nnoise_pred = unet(latent_model_input, t, encoder_hidden_states=text_emb)\n// after\nnoise_pred = unet(latent_model_input, t, encoder_hidden_states=text_emb, class_labels=class_labels)","handlingStrategy":"validation","validationCode":"if unet.config.num_class_embeds and class_labels is None:\n    raise ValueError('This UNet requires class_labels (num_class_embeds > 0)')\nnoise_pred = unet(sample, t, encoder_hidden_states=emb, class_labels=class_labels)","typeGuard":"def needs_class_labels(unet) -> bool:\n    return bool(getattr(unet.config, 'num_class_embeds', 0))","tryCatchPattern":null,"preventionTips":["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"],"tags":["diffusers","unet","missing-argument","conditioning"],"backgroundTag":"missing-required-argument","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}