{"record":{"id":"c89e49fa11d2cd9f","repo":"invoke-ai/InvokeAI","slug":"class-labels-should-be-provided-when-num-class-emb-c89e49","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/util/hotfixes.py","lineNumber":673,"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            class_emb = self.class_embedding(class_labels).to(dtype=self.dtype)\n            emb = emb + class_emb\n\n        if \"addition_embed_type\" in self.config:\n            if self.config.addition_embed_type == \"text\":\n                aug_emb = self.add_embedding(encoder_hidden_states)\n\n            elif self.config.addition_embed_type == \"text_time\":\n                if \"text_embeds\" not in added_cond_kwargs:\n                    raise ValueError(\n                        f\"{self.__class__} has the config param `addition_embed_type` set to 'text_time' which \\\n                            requires the keyword argument `text_embeds` to be passed in `added_cond_kwargs`\"\n                    )\n                text_embeds = added_cond_kwargs.get(\"text_embeds\")","sourceCodeStart":655,"sourceCodeEnd":691,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/util/hotfixes.py#L655-L691","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nunet(sample, timestep, encoder_hidden_states)\n// after\nunet(sample, timestep, encoder_hidden_states, class_labels=torch.tensor([0], device=sample.device))","handlingStrategy":"validation","validationCode":"needs_labels = getattr(unet.config, 'num_class_embeds', 0) > 0\nif needs_labels and class_labels is None:\n    raise ValueError(\"this UNet requires class_labels\")","typeGuard":"def class_conditioning_ok(unet, class_labels):\n    return getattr(unet.config, 'num_class_embeds', 0) == 0 or class_labels is not None","tryCatchPattern":"try:\n    noise_pred = unet(sample, t, encoder_hidden_states, class_labels=class_labels)\nexcept ValueError as e:\n    logger.error(\"class conditioning mismatch: %s\", e)\n    raise","preventionTips":["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"],"tags":["valueerror","unet","missing-argument"],"backgroundTag":"missing-required-argument","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}