invoke-ai/InvokeAI · error · ValueError

Wan reference condition requires {expected}; got {condition.

Error message

Wan reference condition requires {expected}; got {condition.shape[2]}.

What it means

The frame (temporal) dimension of the reference condition, shape[2], must equal the number of latent frames the denoise run expects (1 for a single reference image frame, otherwise the computed latent frame count of the video). Mismatches are rejected with a message stating the expected count.

Source

Thrown at invokeai/app/invocations/wan_denoise.py:111


def _validate_ref_condition_shape(
    condition: torch.Tensor,
    *,
    channels: int,
    frames: int,
    height: int,
    width: int,
) -> None:
    if condition.ndim != 5:
        raise ValueError(f"Wan reference condition must be a 5D tensor; got shape {tuple(condition.shape)}.")
    if condition.shape[0] != 1:
        raise ValueError(f"Wan reference condition requires batch size 1; got {condition.shape[0]}.")
    if condition.shape[1] != channels:
        raise ValueError(f"Wan reference condition requires {channels} channels; got {condition.shape[1]}.")
    if condition.shape[2] != frames:
        expected = "a single latent frame" if frames == 1 else f"{frames} latent frames"
        raise ValueError(f"Wan reference condition requires {expected}; got {condition.shape[2]}.")
    if condition.shape[3:] != (height, width):
        raise ValueError(
            f"Wan reference condition requires {width}x{height} latent spatial dimensions; "
            f"got {condition.shape[4]}x{condition.shape[3]}."
        )


def _scheduler_path_for_transformer(context: InvocationContext, transformer_field: WanTransformerField) -> Path | None:
    """Return the on-disk ``scheduler/`` directory for the main model, or None."""
    config = context.models.get_config(transformer_field.transformer)
    model_root = context.models.get_absolute_path(config)
    if model_root.is_file():
        return None
    candidate = model_root / "scheduler"
    if (candidate / "scheduler_config.json").exists():
        return candidate
    return None

View on GitHub (pinned to 0b6a024f2f)

Solutions

  1. Slice the condition to the expected latent frames: condition[:, :, :frames]
  2. For a single reference image, ensure the temporal dim is exactly 1 (e.g. take latents[:, :, 0:1])
  3. Recompute the expected latent frame count from the requested video frames and match it
  4. Regenerate the condition with the correct num_frames in the conditioning node

Example fix

// before
condition = video_latents  # T = 21 latent frames, expected 1
// after
condition = video_latents[:, :, :1]  # single latent frame
Defensive patterns

Strategy: validation

Validate before calling

expected_latent_frames = 1 if is_reference_image else (num_frames - 1) // 4 + 1  # per variant's temporal compression
if condition.shape[2] != expected_latent_frames:
    condition = condition[:, :, :expected_latent_frames]

Type guard

def has_expected_frames(t, frames: int) -> bool:
    import torch
    return isinstance(t, torch.Tensor) and t.ndim == 5 and t.shape[2] == frames

Try / catch

try:
    result = denoise.invoke(context)
except ValueError as e:
    if "latent frame" in str(e):
        expected = int(str(e).split('requires ')[1].split(' latent')[0]) if 'latent frames' in str(e) else 1
        denoise.ref_condition = denoise.ref_condition[:, :, :expected]
        result = denoise.invoke(context)
    else:
        raise

Prevention

When it happens

Trigger: Passing a multi-frame video latent as a ref condition where a single latent frame is expected (or vice versa), misconfiguring the latent frame count / num_frames so the computed latent frames differ from the condition's, Wan 2.2 latent temporal compression (4x) miscalculations.

Common situations: Using an image-latent squeezed into a 5D shape with T>1 by mistake, supplying a clip's full latent sequence as a reference for a short denoise, off-by-one in frames-to-latent-frames conversion ((frames-1)/4+1 style formulas).

Understand the failure class

Background: Tensor shape mismatch errors ("must have shape", "expected shape ... got ..."): when tensor dimensions disagree with what an op or layer was told to expect — this error's family across 6 libraries.

Related errors

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