invoke-ai/InvokeAI · error · ValueError

Didn't get guidance strength for guidance distilled model.

Error message

Didn't get guidance strength for guidance distilled model.

What it means

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.

Source

Thrown at invokeai/backend/flux/model.py:114

        timesteps: Tensor,
        y: Tensor,
        guidance: Tensor | None,
        timestep_index: int,
        total_num_timesteps: int,
        controlnet_double_block_residuals: list[Tensor] | None,
        controlnet_single_block_residuals: list[Tensor] | None,
        ip_adapter_extensions: list[XLabsIPAdapterExtension],
        regional_prompting_extension: RegionalPromptingExtension,
    ) -> Tensor:
        if img.ndim != 3 or txt.ndim != 3:
            raise ValueError("Input img and txt tensors must have 3 dimensions.")

        # running on sequences img
        img = self.img_in(img)
        vec = self.time_in(timestep_embedding(timesteps, 256))
        if self.params.guidance_embed:
            if guidance is None:
                raise ValueError("Didn't get guidance strength for guidance distilled model.")
            vec = vec + self.guidance_in(timestep_embedding(guidance, 256))
        vec = vec + self.vector_in(y)
        txt = self.txt_in(txt)

        ids = torch.cat((txt_ids, img_ids), dim=1)
        pe = self.pe_embedder(ids)

        # Validate double_block_residuals shape.
        if controlnet_double_block_residuals is not None:
            assert len(controlnet_double_block_residuals) == len(self.double_blocks)
        for block_index, block in enumerate(self.double_blocks):
            assert isinstance(block, DoubleStreamBlock)
            img, txt = CustomDoubleStreamBlockProcessor.custom_double_block_forward(
                timestep_index=timestep_index,
                total_num_timesteps=total_num_timesteps,
                block_index=block_index,
                block=block,
                img=img,

View on GitHub (pinned to 0b6a024f2f)

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)

Example fix

// before
output = model(img=img, img_ids=img_ids, txt=txt, txt_ids=txt_ids, y=vec, timesteps=timesteps)
// after
guidance = torch.full((img.shape[0],), 3.5, device=img.device, dtype=torch.float32)
output = model(img=img, img_ids=img_ids, txt=txt, txt_ids=txt_ids, y=vec, timesteps=timesteps, guidance=guidance)

Defensive patterns

Strategy: validation

Validate before calling

if getattr(model.params, 'guidance_embed', False):
    assert guidance is not None, "guidance is required for distilled FLUX models"

Type guard

def needs_guidance(params) -> bool:
    return bool(getattr(params, 'guidance_embed', False))

Try / catch

try:
    output = model(..., guidance=guidance)
except ValueError as e:
    if "guidance strength" in str(e):
        guidance = torch.full((batch,), 3.5, device=device)
        output = model(..., guidance=guidance)
    else:
        raise

Prevention

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

When it happens

Trigger: 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.

Common situations: Custom sampling loops skipping the guidance argument; migrating from a CFG-based model to Flux dev; calling forward in tests with minimal args.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/579e847b7102947b. Report an issue: GitHub.