{"record":{"id":"d092f8248a230171","repo":"invoke-ai/InvokeAI","slug":"didn-t-get-guidance-strength-for-guidance-distille","errorCode":null,"errorMessage":"Didn't get guidance strength for guidance distilled model.","messagePattern":"Didn't get guidance strength for guidance distilled model\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/flux/controlnet/instantx_controlnet_flux.py","lineNumber":130,"sourceCode":"        img_ids: torch.Tensor,\n        txt: torch.Tensor,\n        txt_ids: torch.Tensor,\n        timesteps: torch.Tensor,\n        y: torch.Tensor,\n        guidance: torch.Tensor | None = None,\n    ) -> InstantXControlNetFluxOutput:\n        if img.ndim != 3 or txt.ndim != 3:\n            raise ValueError(\"Input img and txt tensors must have 3 dimensions.\")\n\n        img = self.img_in(img)\n\n        # Add controlnet_cond embedding.\n        img = img + self.controlnet_x_embedder(controlnet_cond)\n\n        vec = self.time_in(timestep_embedding(timesteps, 256))\n        if self.params.guidance_embed:\n            if guidance is None:\n                raise ValueError(\"Didn't get guidance strength for guidance distilled model.\")\n            vec = vec + self.guidance_in(timestep_embedding(guidance, 256))\n        vec = vec + self.vector_in(y)\n        txt = self.txt_in(txt)\n\n        # If this is a union ControlNet, then concat the control mode embedding to the T5 text embedding.\n        if self.is_union:\n            if controlnet_mode is None:\n                # We allow users to enter 'None' as the controlnet_mode if they don't want to worry about this input.\n                # We've chosen to use a zero-embedding in this case.\n                zero_index = torch.zeros([1, 1], dtype=torch.long, device=txt.device)\n                controlnet_mode_emb = torch.zeros_like(self.controlnet_mode_embedder(zero_index))\n            else:\n                controlnet_mode_emb = self.controlnet_mode_embedder(controlnet_mode)\n            txt = torch.cat([controlnet_mode_emb, txt], dim=1)\n            txt_ids = torch.cat([txt_ids[:, :1, :], txt_ids], dim=1)\n        else:\n            assert controlnet_mode is None\n","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/flux/controlnet/instantx_controlnet_flux.py#L112-L148","documentation":"This Flux ControlNet variant is built with params.guidance_embed=True, meaning the model was guidance-distilled (guidance scale baked into the model via an extra embedding) and therefore needs the per-step guidance vector at every forward call. When guidance_embed is enabled but the guidance argument is None, the model cannot compute vec and raises instead of silently producing wrong results.","triggerScenarios":"Calling InstantXControlNetFlux.forward(...) with guidance=None (the default) while the loaded params have guidance_embed=True — i.e. using a Flux dev (guidance-distilled) checkpoint and omitting the guidance tensor.","commonSituations":"Reusing inference code written for guidance-distillation-free models (schnell) where guidance is not passed; pipeline refactor that dropped the guidance argument; loading a dev checkpoint but wiring a schnell-style scheduler that never produces guidance values.","solutions":["Pass a guidance tensor, e.g. guidance=torch.full((batch,), 3.5, device=img.device) scaled per your CFG schedule, whenever params.guidance_embed is True.","Load a checkpoint/config with guidance_embed=False if you want to run without guidance (e.g. schnell-style) and pass guidance=None.","Check self.params.guidance_embed at the call site and branch your pipeline accordingly.","Fix config loading so guidance_embed reflects the actual checkpoint metadata."],"exampleFix":"// before\nout = controlnet(img=img, txt=txt, controlnet_cond=cond, txt_ids=txt_ids, img_ids=img_ids, timesteps=t, y=y)  # guidance omitted\n// after\nguidance = torch.full((img.shape[0],), 3.5, device=img.device, dtype=img.dtype)\nout = controlnet(img=img, txt=txt, controlnet_cond=cond, txt_ids=txt_ids, img_ids=img_ids, timesteps=t, y=y, guidance=guidance)","handlingStrategy":"validation","validationCode":"if controlnet.params.guidance_embed:\n    assert guidance is not None, \"guidance tensor required for guidance-distilled (dev) Flux checkpoints\"","typeGuard":"def needs_guidance(params) -> bool:\n    return params.guidance_embed","tryCatchPattern":"try:\n    out = controlnet(..., guidance=guidance)\nexcept ValueError as e:\n    if \"guidance strength\" in str(e):\n        guidance = torch.full((batch,), 3.5, device=device)\n        out = controlnet(..., guidance=guidance)\n    else:\n        raise","preventionTips":["Check params.guidance_embed once at pipeline setup and branch the call signature accordingly.","Default guidance to 3.5 (Flux dev's training value) when distillation is enabled.","Use schnell checkpoints (guidance_embed=False) if your pipeline never produces guidance values."],"tags":["flux","guidance","missing-argument","controlnet"],"backgroundTag":"missing-guidance-embedding-input","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}