invoke-ai/InvokeAI · error · ValueError

Reference-image num_frames ({self.ref_image.num_frames}) mus

Error message

Reference-image num_frames ({self.ref_image.num_frames}) must match denoise num_frames ({self.num_frames}). Re-run the Reference Image - Wan 2.2 node with num_frames={self.num_frames}.

What it means

For I2V-A14B, the reference condition tensor is encoded per pixel-frame count, so the encoder's num_frames must equal the denoise node's num_frames or the time-axis shapes won't match. InvokeAI raises ValueError telling the user exactly which num_frames to re-encode with. TI2V-5B is exempt because its condition is always single-frame.

Source

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

        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}."
                )
            ref_condition = context.tensors.load(self.ref_image.condition_tensor_name).to(
                device=device, dtype=inference_dtype
            )
            _validate_ref_condition_shape(
                ref_condition,
                channels=48 if variant == WanVariantType.TI2V_5B else 20,
                frames=1 if variant == WanVariantType.TI2V_5B else num_latent_frames_for(self.num_frames),
                height=self.height // spatial_scale,
                width=self.width // spatial_scale,
            )

        scheduler.set_timesteps(num_inference_steps=self.steps, device=device)
        timesteps = scheduler.timesteps
        total_steps = len(timesteps)

View on GitHub (pinned to 0b6a024f2f)

Solutions

Re-run the Reference Image - Wan 2.2 node with num_frames equal to the denoise node's num_frames (the error message states the exact value).
Keep both nodes' num_frames linked to the same source (e.g. a single integer primitive feeding both).
Use TI2V-5B if you need output length to vary independently of the encoded reference.

Example fix

// before
ref_encoder.num_frames = 81
denoise.num_frames = 61
// after
ref_encoder.num_frames = 61
denoise.num_frames = 61

Defensive patterns

Strategy: validation

Validate before calling

if variant == WanVariantType.I2V_A14B and ref_image.num_frames != num_frames:
    ref_condition = re_encode_reference(num_frames=num_frames)  # re-run encoder with denoise's num_frames

Try / catch

try:
    tensor = denoise._run_diffusion(context)
except ValueError as e:
    if "must match denoise" in str(e) and "num_frames" in str(e):
        ref_condition = re_encode_reference(num_frames=num_frames)
    else:
        raise

Prevention

Feed num_frames from one primitive into both reference encoder and denoise nodes.
Re-encode the reference image after any clip-length change.
On TI2V-5B this check is skipped (single-frame condition), so mismatches only bite A14B.

When it happens

Trigger: Running the Reference Image node with num_frames=81 but the Wan Video Denoise (I2V-A14B variant) with num_frames=61, then wiring the condition into denoise.

Common situations: Iterating on clip length in the denoise node without re-running the encoder; different num_frames defaults in the two nodes when assembling a workflow.

Related errors

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