invoke-ai/InvokeAI · error · ValueError

Reference-image conditioning is only supported by Wan 2.2 I2

Error message

Reference-image conditioning is only supported by Wan 2.2 I2V variants (I2V-A14B or TI2V-5B). The selected transformer is {variant.value!r}. Remove the Reference Image input or load an I2V variant.

What it means

Reference-image (subject/character) conditioning in Wan 2.2 is implemented only in the I2V variants (I2V-A14B and TI2V-5B), which accept an extra condition tensor alongside the noise latents. Text-to-video (T2V) transformers have no such input path, so InvokeAI raises ValueError when a ref image is connected to a non-I2V transformer.

Source

Thrown at invokeai/app/invocations/wan_video_denoise.py:207

        do_cfg = self.negative_conditioning is not None and (self.guidance_scale != 1.0 or low_cfg_enabled)
        neg_cond: WanConditioningInfo | None = None
        if do_cfg:
            assert self.negative_conditioning is not None
            neg_cond = self._load_conditioning(
                context, self.negative_conditioning, device=device, dtype=inference_dtype
            )

        # I2V condition tensor. Two flavours:
        #   * A14B I2V — [1, 20, T_lat, H_lat, W_lat] (4 mask + 16 latent channels).
        #     Concatenated to noise latents along the channel dim each step → 36ch.
        #   * TI2V-5B I2V — [1, 48, 1, H_lat, W_lat] (single latent frame, same
        #     channel count as the noise latents). Blended with noise via a
        #     first_frame_mask at every step (expand_timesteps path).
        # Variant dispatch happens via the condition tensor's channel count below.
        ref_condition: torch.Tensor | None = None
        if self.ref_image is not None:
            if variant not in (WanVariantType.I2V_A14B, WanVariantType.TI2V_5B):
                raise ValueError(
                    f"Reference-image conditioning is only supported by Wan 2.2 I2V variants "
                    f"(I2V-A14B or TI2V-5B). The selected transformer is {variant.value!r}. "
                    "Remove the Reference Image input or load an I2V variant."
                )
            if self.ref_image.width != self.width or self.ref_image.height != self.height:
                raise ValueError(
                    f"Reference-image dimensions ({self.ref_image.width}x{self.ref_image.height}) must "
                    f"match denoise dimensions ({self.width}x{self.height})."
                )
            # A14B encodes one condition tensor per pixel-frame count, so the
            # encoder's num_frames must match. TI2V-5B's condition is always
            # single-frame regardless of the output length, so the field's
            # num_frames is informational only and we skip this check.
            if variant == WanVariantType.I2V_A14B and self.ref_image.num_frames != self.num_frames:
                raise ValueError(
                    f"Reference-image num_frames ({self.ref_image.num_frames}) must match denoise "
                    f"num_frames ({self.num_frames}). Re-run the Reference Image - Wan 2.2 node with "
                    f"num_frames={self.num_frames}."

View on GitHub (pinned to 0b6a024f2f)

Solutions

  1. Load a Wan 2.2 I2V transformer (I2V-A14B or TI2V-5B) in the denoise node's transformer input.
  2. Remove the Reference Image input if you intend to stay on T2V.
  3. Verify the variant reported in the error matches the model you think you downloaded; re-install the I2V checkpoint if it shows 't2v'.

Example fix

// before
transformer = wan_2_2_t2v_a14b  # variant 't2v-a14b'
// after
transformer = wan_2_2_i2v_a14b  # variant 'i2v-a14b'
Defensive patterns

Strategy: validation

Validate before calling

if ref_image is not None and variant not in (WanVariantType.I2V_A14B, WanVariantType.TI2V_5B):
    ref_image = None  # or load an I2V transformer instead

Type guard

def supports_ref_conditioning(variant: WanVariantType) -> bool:
    return variant in (WanVariantType.I2V_A14B, WanVariantType.TI2V_5B)

Try / catch

try:
    tensor = denoise._run_diffusion(context)
except ValueError as e:
    if "Reference-image conditioning is only supported" in str(e):
        ref_image = None  # proceed without reference conditioning
    else:
        raise

Prevention

When it happens

Trigger: Connecting a Reference Image output to Wan Video Denoise while the loaded transformer's variant is T2V (e.g. Wan2.1-T2V or Wan2.2-T2V-A14B).

Common situations: Users download the T2V checkpoint (often the most publicized) and then try to add a reference image for character consistency without realizing it requires the I2V variant.

Related errors

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