{"record":{"id":"9eed014a98442316","repo":"invoke-ai/InvokeAI","slug":"reference-image-conditioning-is-only-supported-by-9eed01","errorCode":null,"errorMessage":"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.","messagePattern":"Reference-image conditioning is only supported by Wan 2\\.2 I2V variants \\(I2V-A14B or TI2V-5B\\)\\. The selected transformer is (.+?)\\. Remove the Reference Image input or load an I2V variant\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/app/invocations/wan_video_denoise.py","lineNumber":207,"sourceCode":"        do_cfg = self.negative_conditioning is not None and (self.guidance_scale != 1.0 or low_cfg_enabled)\n        neg_cond: WanConditioningInfo | None = None\n        if do_cfg:\n            assert self.negative_conditioning is not None\n            neg_cond = self._load_conditioning(\n                context, self.negative_conditioning, device=device, dtype=inference_dtype\n            )\n\n        # I2V condition tensor. Two flavours:\n        #   * A14B I2V — [1, 20, T_lat, H_lat, W_lat] (4 mask + 16 latent channels).\n        #     Concatenated to noise latents along the channel dim each step → 36ch.\n        #   * TI2V-5B I2V — [1, 48, 1, H_lat, W_lat] (single latent frame, same\n        #     channel count as the noise latents). Blended with noise via a\n        #     first_frame_mask at every step (expand_timesteps path).\n        # Variant dispatch happens via the condition tensor's channel count below.\n        ref_condition: torch.Tensor | None = None\n        if self.ref_image is not None:\n            if variant not in (WanVariantType.I2V_A14B, WanVariantType.TI2V_5B):\n                raise ValueError(\n                    f\"Reference-image conditioning is only supported by Wan 2.2 I2V variants \"\n                    f\"(I2V-A14B or TI2V-5B). The selected transformer is {variant.value!r}. \"\n                    \"Remove the Reference Image input or load an I2V variant.\"\n                )\n            if self.ref_image.width != self.width or self.ref_image.height != self.height:\n                raise ValueError(\n                    f\"Reference-image dimensions ({self.ref_image.width}x{self.ref_image.height}) must \"\n                    f\"match denoise dimensions ({self.width}x{self.height}).\"\n                )\n            # A14B encodes one condition tensor per pixel-frame count, so the\n            # encoder's num_frames must match. TI2V-5B's condition is always\n            # single-frame regardless of the output length, so the field's\n            # num_frames is informational only and we skip this check.\n            if variant == WanVariantType.I2V_A14B and self.ref_image.num_frames != self.num_frames:\n                raise ValueError(\n                    f\"Reference-image num_frames ({self.ref_image.num_frames}) must match denoise \"\n                    f\"num_frames ({self.num_frames}). Re-run the Reference Image - Wan 2.2 node with \"\n                    f\"num_frames={self.num_frames}.\"","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/app/invocations/wan_video_denoise.py#L189-L225","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Load a Wan 2.2 I2V transformer (I2V-A14B or TI2V-5B) in the denoise node's transformer input.","Remove the Reference Image input if you intend to stay on T2V.","Verify the variant reported in the error matches the model you think you downloaded; re-install the I2V checkpoint if it shows 't2v'."],"exampleFix":"// before\ntransformer = wan_2_2_t2v_a14b  # variant 't2v-a14b'\n// after\ntransformer = wan_2_2_i2v_a14b  # variant 'i2v-a14b'","handlingStrategy":"validation","validationCode":"if ref_image is not None and variant not in (WanVariantType.I2V_A14B, WanVariantType.TI2V_5B):\n    ref_image = None  # or load an I2V transformer instead","typeGuard":"def supports_ref_conditioning(variant: WanVariantType) -> bool:\n    return variant in (WanVariantType.I2V_A14B, WanVariantType.TI2V_5B)","tryCatchPattern":"try:\n    tensor = denoise._run_diffusion(context)\nexcept ValueError as e:\n    if \"Reference-image conditioning is only supported\" in str(e):\n        ref_image = None  # proceed without reference conditioning\n    else:\n        raise","preventionTips":["Only attach reference images to I2V-A14B or TI2V-5B transformers.","Check the transformer's variant field when building Wan workflows.","Keep separate T2V and I2V workflow templates to avoid miswiring."],"tags":["validation","reference-image","variant-mismatch","wan"],"backgroundTag":"unsupported-feature-combination","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}