invoke-ai/InvokeAI · error · ValueError

Negative text conditioning is required when cfg_scale is not

Error message

Negative text conditioning is required when cfg_scale is not 1.0.

What it means

In flux2 denoise, when a per-step classifier-free-guidance scale deviates from 1.0, the loop must run the model a second time on negative text conditioning (neg_txt). If cfg_scale != 1.0 but neg_txt is None, CFG cannot be computed, so denoise raises ValueError early instead of producing incorrect output.

Source

Thrown at invokeai/backend/flux2/denoise.py:171

                txt_ids=txt_ids,
                guidance=guidance_vec,
                joint_attention_kwargs=pos_joint_attention_kwargs,
                return_dict=False,
            )

            # Extract the sample from the output (return_dict=False returns tuple)
            pred = output[0] if isinstance(output, tuple) else output

            # Drop the prediction for the reference tokens - they are context, not sampled state.
            if img_cond_seq is not None:
                pred = pred[:, :original_seq_len]

            step_cfg_scale = cfg_scale[min(user_step, len(cfg_scale) - 1)]

            # Apply CFG if scale is not 1.0
            if not math.isclose(step_cfg_scale, 1.0):
                if neg_txt is None:
                    raise ValueError("Negative text conditioning is required when cfg_scale is not 1.0.")

                neg_output = model(
                    hidden_states=img_input,
                    encoder_hidden_states=neg_txt,
                    timestep=t_vec,
                    img_ids=model_img_ids,
                    txt_ids=neg_txt_ids if neg_txt_ids is not None else txt_ids,
                    guidance=guidance_vec,
                    return_dict=False,
                )

                neg_pred = neg_output[0] if isinstance(neg_output, tuple) else neg_output
                if img_cond_seq is not None:
                    neg_pred = neg_pred[:, :original_seq_len]
                pred = neg_pred + step_cfg_scale * (pred - neg_pred)

            # Use scheduler.step() for the update
            step_output = scheduler.step(model_output=pred, timestep=timestep, sample=img)

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Encode the negative prompt and pass its embeddings as neg_txt to denoise
2. Set cfg_scale to 1.0 (or a list of all 1.0s) if you don't want CFG and have no negative prompt
3. Ensure the per-step cfg_scale slice actually equals 1.0 for steps where neg_txt is absent

Example fix

// before
output = denoise(model=..., img=..., cfg_scale=3.5, neg_txt=None, ...)
// after
neg_txt = encode_prompt(negative_prompt)  # encode negative prompt
output = denoise(model=..., img=..., cfg_scale=3.5, neg_txt=neg_txt, ...)

if any(not math.isclose(s, 1.0) for s in (cfg_scale if isinstance(cfg_scale, list) else [cfg_scale])):
    assert neg_txt is not None, "cfg_scale != 1.0 requires neg_txt"

try:
    latents = denoise(..., cfg_scale=cfg_scale, neg_txt=neg_txt)
except ValueError as e:
    if "Negative text conditioning" in str(e):
        neg_txt = encode_prompt("")
        latents = denoise(..., cfg_scale=cfg_scale, neg_txt=neg_txt)
    else:
        raise

When it happens

Trigger: Calling denoise with cfg_scale (scalar or per-step list) != 1.0 while neg_txt is None — e.g. building text embeddings only for the positive prompt, or omitting negative prompt processing in a custom pipeline around Flux2.

Common situations: Custom Flux2 sampling loops that skip encoding the negative prompt; pipelines migrated from CFG-free Flux.1 where negative conditioning was unused; per-step cfg_scale lists where any step differs from 1.0.

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

• Negative text conditioning is required when cfg_scale is not
• denoising_start ({self.denoising_start}) must be less than d
• denoising_start should be 0 when initial latents are not pro
• cfg_scale must be greater than 1
• Negative conditioning is required when guidance_scale > 1.0

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