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

Source

Thrown at invokeai/backend/flux/controlnet/xlabs_controlnet_flux.py:111

        txt: torch.Tensor,
        txt_ids: torch.Tensor,
        timesteps: torch.Tensor,
        y: torch.Tensor,
        guidance: torch.Tensor | None = None,
    ) -> XLabsControlNetFluxOutput:
        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)
        controlnet_cond = self.input_hint_block(controlnet_cond)
        controlnet_cond = rearrange(controlnet_cond, "b c (h ph) (w pw) -> b (h w) (c ph pw)", ph=2, pw=2)
        controlnet_cond = self.pos_embed_input(controlnet_cond)
        img = img + controlnet_cond
        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)

        block_res_samples: list[torch.Tensor] = []

        for block in self.double_blocks:
            img, txt = block(img=img, txt=txt, vec=vec, pe=pe)
            block_res_samples.append(img)

        controlnet_block_res_samples: list[torch.Tensor] = []
        for block_res_sample, controlnet_block in zip(block_res_samples, self.controlnet_blocks, strict=True):
            block_res_sample = controlnet_block(block_res_sample)
            controlnet_block_res_samples.append(block_res_sample)

View on GitHub (pinned to 0b6a024f2f)

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.

Example fix

// before
out = xlabs_controlnet(img=img, txt=txt, ...)  # guidance defaults to None
// after
guidance = torch.tensor([3.5] * img.shape[0], device=img.device, dtype=img.dtype)
out = xlabs_controlnet(img=img, txt=txt, ..., guidance=guidance)

Defensive patterns

Strategy: validation

Validate before calling

if xlabs_controlnet.params.guidance_embed:
    assert guidance is not None, "guidance tensor required (guidance-distilled checkpoint)"

Type guard

def requires_guidance(model) -> bool:
    return model.params.guidance_embed

Try / catch

try:
    out = xlabs_controlnet(..., guidance=guidance)
except ValueError as e:
    if "guidance strength" in str(e):
        out = xlabs_controlnet(..., guidance=torch.full((img.shape[0],), 3.5, device=img.device))
    else:
        raise

Prevention

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.

When it happens

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

Common situations: 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.

Related errors

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