invoke-ai/InvokeAI · error · ValueError

Initial latents are required when using an inpaint mask (img

Error message

Initial latents are required when using an inpaint mask (img2img inpainting).

What it means

The Wan denoise node supports inpaint masking only in img2img mode: the mask blends the original latents back into regions the mask preserves. If an inpaint mask is connected but there are no initial latents, there is nothing to blend, so the node raises instead of producing meaningless output.

Source

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

                s_0 = float(sigmas[0])
                latents = s_0 * noise + (1.0 - s_0) * init_latents_5d
            else:
                latents = init_latents_5d
        else:
            if self.denoising_start > 1e-5:
                raise ValueError("denoising_start should be 0 when initial latents are not provided.")
            latents = noise

        if total_steps <= 0:
            return latents.squeeze(2)

        # Inpaint extension (4D space — the existing extension is shape-agnostic
        # but operates on the squeezed-T shape we use for masks).
        inpaint_mask = self._prep_inpaint_mask(context, latents.squeeze(2))
        inpaint_extension: RectifiedFlowInpaintExtension | None = None
        if inpaint_mask is not None:
            if init_latents_5d is None:
                raise ValueError("Initial latents are required when using an inpaint mask (img2img inpainting).")
            inpaint_extension = RectifiedFlowInpaintExtension(
                init_latents=init_latents_5d.squeeze(2),
                inpaint_mask=inpaint_mask,
                noise=noise.squeeze(2),
            )

        step_callback = self._build_step_callback(context)

        # Resolve experts and the boundary timestep that triggers the MoE swap.
        #
        # We deliberately do NOT call ``context.models.load(...)`` for the
        # transformer experts here — that would put both ~9 GB GGUF handles
        # in the model cache concurrently. With UMT5-XXL (~10 GB) competing
        # for the same cache, the LRU policy can drop one of them by the
        # time the denoise loop swaps in, producing the
        # "has already been dropped from the RAM cache" warning and forcing
        # a disk reload per swap. The swapper calls ``models.load`` lazily
        # inside each ``get()`` instead, so handles are always fresh.

View on GitHub (pinned to 0b6a024f2f)

Solutions

Connect a source image through Wan Image to Latents into the denoise node's initial latents input
Or disconnect the inpaint mask if you intend pure txt2img generation

Example fix

// before
inpaintMask -> wanDenoise.inpaint_mask, no init latents
// after
image -> wanImageToLatents -> wanDenoise.init_latents AND inpaintMask -> wanDenoise.inpaint_mask

Defensive patterns

Strategy: validation

Validate before calling

if inpaint_mask is not None and init_latents is None:
    raise ValueError("inpaint mask requires initial latents (img2img inpainting)")

Try / catch

try:
    result = wan_denoise.invoke(context)
except ValueError as e:
    if 'inpaint mask' in str(e):
        connect_image_to_latents(...)  # or remove the mask
    else:
        raise

Prevention

Only connect inpaint masks when an image path is wired
Disconnect the mask when converting to txt2img
Verify all denoise inputs in the workflow editor before running

When it happens

Trigger: Connecting an inpaint mask input to a WanDenoise node in text-to-video mode (no image/initial latents); using the mask from an img2img inpaint workflow after removing the image input.

Common situations: Reusing an inpaint workflow template but deleting the image-to-latents path; users expecting mask-based inpainting from pure noise (not supported by this node).

Related errors

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