{"record":{"id":"579e847b7102947b","repo":"invoke-ai/InvokeAI","slug":"didn-t-get-guidance-strength-for-guidance-distille-579e84","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/model.py","lineNumber":114,"sourceCode":"        timesteps: Tensor,\n        y: Tensor,\n        guidance: Tensor | None,\n        timestep_index: int,\n        total_num_timesteps: int,\n        controlnet_double_block_residuals: list[Tensor] | None,\n        controlnet_single_block_residuals: list[Tensor] | None,\n        ip_adapter_extensions: list[XLabsIPAdapterExtension],\n        regional_prompting_extension: RegionalPromptingExtension,\n    ) -> Tensor:\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        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        # Validate double_block_residuals shape.\n        if controlnet_double_block_residuals is not None:\n            assert len(controlnet_double_block_residuals) == len(self.double_blocks)\n        for block_index, block in enumerate(self.double_blocks):\n            assert isinstance(block, DoubleStreamBlock)\n            img, txt = CustomDoubleStreamBlockProcessor.custom_double_block_forward(\n                timestep_index=timestep_index,\n                total_num_timesteps=total_num_timesteps,\n                block_index=block_index,\n                block=block,\n                img=img,","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/flux/model.py#L96-L132","documentation":"This FLUX build uses guidance distillation (params.guidance_embed is True), meaning the guidance scale is an input embedding to the transformer rather than classic CFG. When guidance_embed is enabled, the forward method requires an explicit `guidance` tensor; passing None makes the distilled model ill-defined, so it raises.","triggerScenarios":"Calling Flux.forward with guidance=None on a guidance-distilled checkpoint (FLUX.1 dev/schnell family): invoking forward directly from a custom pipeline that omits guidance, or reusing code written for non-distilled FLUX variants.","commonSituations":"Custom sampling loops skipping the guidance argument; migrating from a CFG-based model to Flux dev; calling forward in tests with minimal args.","solutions":["Pass a guidance tensor, e.g. guidance=torch.tensor([4.0], device=device, dtype=torch.float32) (typical value 3.5–4.0 for FLUX dev)","If you truly don't need guidance embedding, load a variant whose params have guidance_embed=False","Set guidance to 1.0-equivalent behavior by passing the value your pipeline normally uses (default 3.5)"],"exampleFix":"// before\noutput = model(img=img, img_ids=img_ids, txt=txt, txt_ids=txt_ids, y=vec, timesteps=timesteps)\n// after\nguidance = torch.full((img.shape[0],), 3.5, device=img.device, dtype=torch.float32)\noutput = model(img=img, img_ids=img_ids, txt=txt, txt_ids=txt_ids, y=vec, timesteps=timesteps, guidance=guidance)","handlingStrategy":"validation","validationCode":"if getattr(model.params, 'guidance_embed', False):\n    assert guidance is not None, \"guidance is required for distilled FLUX models\"","typeGuard":"def needs_guidance(params) -> bool:\n    return bool(getattr(params, 'guidance_embed', False))","tryCatchPattern":"try:\n    output = model(..., guidance=guidance)\nexcept ValueError as e:\n    if \"guidance strength\" in str(e):\n        guidance = torch.full((batch,), 3.5, device=device)\n        output = model(..., guidance=guidance)\n    else:\n        raise","preventionTips":["Default guidance to 3.5 when building Flux dev pipelines","Check params.guidance_embed before deciding whether to pass guidance","Don't reuse non-distilled model call sites for guidance-distilled checkpoints"],"tags":["flux","guidance-distillation","missing-argument","forward-pass"],"backgroundTag":"missing-required-argument","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}