invoke-ai/InvokeAI · error · ValueError

Wan reference condition must be a 5D tensor; got shape {tupl

Error message

Wan reference condition must be a 5D tensor; got shape {tuple(condition.shape)}.

What it means

_validate_ref_condition_shape checks that the reference condition tensor is a 5D tensor with layout (batch, channels, frames, height, width). Any tensor of rank other than 5 (e.g. a 4D latent or a 3D image tensor) cannot be a Wan video reference condition and is rejected immediately.

Source

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

def _validate_spatial_dimensions(variant: WanVariantType, width: int, height: int) -> None:
    if variant == WanVariantType.TI2V_5B and (width % 32 or height % 32):
        raise ValueError(
            f"TI2V-5B requires width and height to be multiples of 32 (got {width}x{height}). "
            "Wan 2.2-VAE 16x spatial * transformer patch_size 2 = pixel dims must divide by 32."
        )


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)

View on GitHub (pinned to 0b6a024f2f)

Solutions

Insert unsqueeze(2) (or the appropriate reshape) to add the frames dimension and make the tensor 5D
Use the proper Wan reference-image/conditioning node that outputs a 5D latent
Verify the connected node's output shape is (1, C, T, H, W) before the denoise call
If conditioning a single image, route it through the Wan-specific image conditioning path, not the raw latent

Example fix

// before
condition = image_latent            # shape (1, C, H, W)
// after
condition = image_latent.unsqueeze(2)  # shape (1, C, 1, H, W)

Defensive patterns

Strategy: type-guard

Validate before calling

if condition.dim() != 5:
    raise ValueError(f'ref condition must be 5D (B,C,T,H,W); got {tuple(condition.shape)}')

Type guard

def is_5d_condition(t) -> bool:
    import torch
    return isinstance(t, torch.Tensor) and t.ndim == 5

Try / catch

try:
    result = denoise.invoke(context)
except ValueError as e:
    if "must be a 5D tensor" in str(e):
        condition = condition.unsqueeze(2)  # add frame dim if 4D
        result = denoise.invoke(context)
    else:
        raise

Prevention

Always shape ref conditions as (1, C, T, H, W)
Never wire image-only latent nodes directly into Wan video inputs
Log tensor shapes at each graph edge during workflow debugging
Use Wan-specific conditioning nodes that guarantee the 5D layout

When it happens

Trigger: Passing a 4D (B,C,H,W) image latent or a 3D tensor into the reference-condition input of the Wan denoise invocation; wiring an image encoder output directly where a video-shaped latent is expected.

Common situations: Connecting an SD/FLUX-style image latent node to Wan's ref condition input, forgetting the extra frame dimension for video latents, custom scripts building condition tensors with wrong rank.

Related errors

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