invoke-ai/InvokeAI · error · ValueError

A VAE (e.g., controlnet_vae) must be provided to use Kontext

Error message

A VAE (e.g., controlnet_vae) must be provided to use Kontext conditioning.

What it means

Kontext conditioning feeds a reference image into the FLUX transformer, which requires encoding that image through a VAE. The invocation only has a VAE if controlnet_vae is supplied, so when kontext_conditioning is set but controlnet_vae is None it cannot perform the required image-to-latent encoding and raises.

Source

Thrown at invokeai/app/invocations/flux_denoise.py:402

        # Compute the IP-Adapter image prompt clip embeddings.
        # We do this before loading other models to minimize peak memory.
        # TODO(ryand): We should really do this in a separate invocation to benefit from caching.
        ip_adapter_fields = self._normalize_ip_adapter_fields()
        pos_image_prompt_clip_embeds, neg_image_prompt_clip_embeds = self._prep_ip_adapter_image_prompt_clip_embeds(
            ip_adapter_fields, context, device=x.device
        )

        cfg_scale = self.prep_cfg_scale(
            cfg_scale=self.cfg_scale,
            timesteps=timesteps,
            cfg_scale_start_step=self.cfg_scale_start_step,
            cfg_scale_end_step=self.cfg_scale_end_step,
        )

        kontext_extension = None
        if self.kontext_conditioning:
            if not self.controlnet_vae:
                raise ValueError("A VAE (e.g., controlnet_vae) must be provided to use Kontext conditioning.")

            kontext_extension = KontextExtension(
                context=context,
                kontext_conditioning=self.kontext_conditioning
                if isinstance(self.kontext_conditioning, list)
                else [self.kontext_conditioning],
                vae_field=self.controlnet_vae,
                device=device,
                dtype=inference_dtype,
            )

        with ExitStack() as exit_stack:
            # Prepare ControlNet extensions.
            # Note: We do this before loading the transformer model to minimize peak memory (see implementation).
            controlnet_extensions = self._prep_controlnet_extensions(
                context=context,
                exit_stack=exit_stack,
                latent_height=latent_h,

View on GitHub (pinned to 0b6a024f2f)

Solutions

  1. Connect a FLUX-compatible VAE to the controlnet_vae field of the FLUX Denoise invocation.
  2. Remove the kontext_conditioning input if Kontext conditioning is not intended.
  3. Verify the workflow includes the VAE loader node feeding the denoise node's controlnet_vae input.

Example fix

// before
denoise.kontext_conditioning = refImageField; // controlnet_vae unset
// after
denoise.controlnet_vae = vaeField; // VAE required for Kontext image encoding
Defensive patterns

Strategy: validation

Validate before calling

if denoise.kontext_conditioning is not None and denoise.controlnet_vae is None:
    raise ValueError("Kontext conditioning requires a controlnet_vae")

Type guard

def kontext_ready(denoise) -> bool:
    return denoise.kontext_conditioning is None or denoise.controlnet_vae is not None

Try / catch

try:
    result = invoke(denoise)
except ValueError as e:
    if 'must be provided to use Kontext conditioning' in str(e):
        denoise.controlnet_vae = load_vae()
        result = invoke(denoise)
    else:
        raise

Prevention

When it happens

Trigger: Setting the kontext_conditioning field on FLUX Denoise without connecting a VAE to the controlnet_vae field; the check happens in _run_diffusion before building the KontextExtension.

Common situations: Wiring a Kontext reference image but forgetting the auxiliary controlnet_vae input; workflows copied from examples that omit the VAE node; using a model bundle that doesn't include a VAE for Kontext.

Related errors

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