{"record":{"id":"82b3b50bc5879cc7","repo":"invoke-ai/InvokeAI","slug":"didn-t-get-guidance-strength-for-guidance-distille-82b3b5","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/xlabs_controlnet_flux.py","lineNumber":111,"sourceCode":"        txt: torch.Tensor,\n        txt_ids: torch.Tensor,\n        timesteps: torch.Tensor,\n        y: torch.Tensor,\n        guidance: torch.Tensor | None = None,\n    ) -> XLabsControlNetFluxOutput:\n        if img.ndim != 3 or txt.ndim != 3:\n            raise ValueError(\"Input img and txt tensors must have 3 dimensions.\")\n\n        # running on sequences img\n        img = self.img_in(img)\n        controlnet_cond = self.input_hint_block(controlnet_cond)\n        controlnet_cond = rearrange(controlnet_cond, \"b c (h ph) (w pw) -> b (h w) (c ph pw)\", ph=2, pw=2)\n        controlnet_cond = self.pos_embed_input(controlnet_cond)\n        img = img + controlnet_cond\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        ids = torch.cat((txt_ids, img_ids), dim=1)\n        pe = self.pe_embedder(ids)\n\n        block_res_samples: list[torch.Tensor] = []\n\n        for block in self.double_blocks:\n            img, txt = block(img=img, txt=txt, vec=vec, pe=pe)\n            block_res_samples.append(img)\n\n        controlnet_block_res_samples: list[torch.Tensor] = []\n        for block_res_sample, controlnet_block in zip(block_res_samples, self.controlnet_blocks, strict=True):\n            block_res_sample = controlnet_block(block_res_sample)\n            controlnet_block_res_samples.append(block_res_sample)\n","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/flux/controlnet/xlabs_controlnet_flux.py#L93-L129","documentation":"This model uses guidance embeddings (params.guidance_embed=True, i.e. a guidance-distilled Flux checkpoint), so forward() must receive the guidance strength tensor each step. With guidance_embed enabled and guidance=None it cannot build the conditioning vector vec and raises rather than degrading silently.","triggerScenarios":"Calling XLabsControlNetFlux.forward(...) without the guidance argument (or passing None) while the instantiated params have guidance_embed=True — typical when running a Flux dev checkpoint through an inference path that omits guidance.","commonSituations":"Schnell-style pipelines (which don't pass guidance) wired to a dev checkpoint; IP-Adapter/ControlNet demo code copied from non-distilled examples; config where guidance_embed wasn't set to False for a non-distilled model.","solutions":["Pass guidance as a tensor of per-sample strengths, e.g. torch.full((batch,), 3.5), when params.guidance_embed is True.","Set guidance_embed=False in params when using a non-distilled checkpoint so guidance may be None.","Branch in the caller: if controlnet.params.guidance_embed: provide guidance tensor.","Verify checkpoint metadata drives guidance_embed instead of a hardcoded default."],"exampleFix":"// before\nout = xlabs_controlnet(img=img, txt=txt, ...)  # guidance defaults to None\n// after\nguidance = torch.tensor([3.5] * img.shape[0], device=img.device, dtype=img.dtype)\nout = xlabs_controlnet(img=img, txt=txt, ..., guidance=guidance)","handlingStrategy":"validation","validationCode":"if xlabs_controlnet.params.guidance_embed:\n    assert guidance is not None, \"guidance tensor required (guidance-distilled checkpoint)\"","typeGuard":"def requires_guidance(model) -> bool:\n    return model.params.guidance_embed","tryCatchPattern":"try:\n    out = xlabs_controlnet(..., guidance=guidance)\nexcept ValueError as e:\n    if \"guidance strength\" in str(e):\n        out = xlabs_controlnet(..., guidance=torch.full((img.shape[0],), 3.5, device=img.device))\n    else:\n        raise","preventionTips":["Inspect params.guidance_embed at model load and record it in your pipeline config.","Always pass guidance for dev (distilled) checkpoints; default 3.5.","Set guidance_embed=False explicitly for schnell-style checkpoints."],"tags":["flux","guidance","missing-argument","xlabs"],"backgroundTag":"missing-guidance-embedding-input","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}