{"record":{"id":"13439fcacfd449ac","repo":"invoke-ai/InvokeAI","slug":"negative-text-conditioning-is-required-when-cfg-sc","errorCode":null,"errorMessage":"Negative text conditioning is required when cfg_scale is not 1.0.","messagePattern":"Negative text conditioning is required when cfg_scale is not 1\\.0\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/flux/denoise.py","lineNumber":177,"sourceCode":"                    timesteps=t_vec,\n                    guidance=guidance_vec,\n                    timestep_index=user_step,\n                    total_num_timesteps=total_steps,\n                    controlnet_double_block_residuals=merged_controlnet_residuals.double_block_residuals,\n                    controlnet_single_block_residuals=merged_controlnet_residuals.single_block_residuals,\n                    ip_adapter_extensions=pos_ip_adapter_extensions,\n                    regional_prompting_extension=pos_regional_prompting_extension,\n                )\n\n                if img_cond_seq is not None:\n                    pred = pred[:, :original_seq_len]\n\n                # Get CFG scale for current user step\n                step_cfg_scale = cfg_scale[min(user_step, len(cfg_scale) - 1)]\n\n                if not math.isclose(step_cfg_scale, 1.0):\n                    if neg_regional_prompting_extension is None:\n                        raise ValueError(\"Negative text conditioning is required when cfg_scale is not 1.0.\")\n\n                    neg_img_input = img\n                    neg_img_input_ids = img_ids\n\n                    if img_cond is not None:\n                        neg_img_input = torch.cat((neg_img_input, img_cond), dim=-1)\n\n                    if img_cond_seq is not None:\n                        neg_img_input = torch.cat((neg_img_input, img_cond_seq), dim=1)\n                        neg_img_input_ids = torch.cat((neg_img_input_ids, img_cond_seq_ids), dim=1)\n\n                    neg_pred = model(\n                        img=neg_img_input,\n                        img_ids=neg_img_input_ids,\n                        txt=neg_regional_prompting_extension.regional_text_conditioning.t5_embeddings,\n                        txt_ids=neg_regional_prompting_extension.regional_text_conditioning.t5_txt_ids,\n                        y=neg_regional_prompting_extension.regional_text_conditioning.clip_embeddings,\n                        timesteps=t_vec,","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/flux/denoise.py#L159-L195","documentation":"In Flux denoise_sampling_region (denoise.py), when the per-step CFG scale is not 1.0 the sampler must also run a negative (unconditional) prediction, which requires negative text conditioning supplied via a neg_regional_prompting_extension. When a step's cfg_scale != 1.0 and that extension is None, the sampler cannot form the negative pass and raises. CFG == 1.0 means no negative branch is needed, hence the conditional check.","triggerScenarios":"Calling denoise() with a cfg_scale (scalar or per-step schedule) whose value at some step is not 1.0 while neg_regional_prompting_extension is None — e.g. passing cfg_scale=3.5 without building negative conditioning.","commonSituations":"Users enabling CFG in a Flux pipeline that was set up without a negative prompt/region extension; per-step CFG schedules where a later step exceeds 1.0; region-based prompting setups lacking the negative extension object.","solutions":["Provide a negative regional prompting extension (with negative text embeddings) whenever cfg_scale != 1.0.","Keep cfg_scale at 1.0 (guidance-distilled Flux models are trained to run without CFG) if no negative conditioning is available.","Build the negative prompt embeddings in your pipeline before denoising and pass them through.","If using a per-step cfg_scale list, ensure every entry that exceeds 1.0 is accompanied by negative conditioning, or clamp them to 1.0."],"exampleFix":"// before\nresult = denoise(..., cfg_scale=4.0, neg_regional_prompting_extension=None)\n// after\nneg_ext = build_neg_regional_prompting_extension(negative_prompt=\"blurry, low quality\", ...)\nresult = denoise(..., cfg_scale=4.0, neg_regional_prompting_extension=neg_ext)","handlingStrategy":"validation","validationCode":"if any(s != 1.0 for s in (cfg_scale if isinstance(cfg_scale, list) else [cfg_scale])):\n    assert neg_regional_prompting_extension is not None, \\\n        \"cfg_scale != 1.0 requires negative text conditioning\"","typeGuard":"def cfg_needs_negative(cfg_scale, neg_ext) -> bool:\n    values = cfg_scale if isinstance(cfg_scale, list) else [cfg_scale]\n    return any(s != 1.0 for s in values) and neg_ext is None","tryCatchPattern":"try:\n    result = denoise(..., cfg_scale=cfg_scale, neg_regional_prompting_extension=neg_ext)\nexcept ValueError as e:\n    if \"Negative text conditioning is required\" in str(e):\n        raise RuntimeError(\"Enable CFG only with a negative prompt / conditioning extension configured\") from e\n    raise","preventionTips":["Keep cfg_scale at 1.0 for guidance-distilled Flux unless you have a negative prompt configured.","Validate per-step CFG schedules against the presence of negative conditioning before denoising.","Build negative text embeddings in the text-encoding stage, not inside the sampling loop."],"tags":["cfg","flux","missing-conditioning","denoising"],"backgroundTag":"negative-conditioning-required-for-cfg","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}