invoke-ai/InvokeAI · error · ValueError

Initial latents are required when using an inpaint mask (ima

Error message

Initial latents are required when using an inpaint mask (image-to-image inpainting)

What it means

The inpaint extension composites the original latents back under the mask during denoising, so it requires init_latents to exist. If an inpaint mask is attached but no initial latents were provided, _run_diffusion raises ValueError, since image-to-image inpainting cannot operate from pure noise.

Source

Thrown at invokeai/app/invocations/z_image_denoise.py:395

                latents = s_0 * noise + (1.0 - s_0) * init_latents
            else:
                latents = init_latents
        else:
            if self.denoising_start > 1e-5:
                raise ValueError("denoising_start should be 0 when initial latents are not provided.")
            assert noise is not None
            latents = noise

        # Short-circuit if no denoising steps
        if total_steps <= 0:
            return latents

        # Prepare inpaint extension
        inpaint_mask = self._prep_inpaint_mask(context, latents)
        inpaint_extension: RectifiedFlowInpaintExtension | None = None
        if inpaint_mask is not None:
            if init_latents is None:
                raise ValueError("Initial latents are required when using an inpaint mask (image-to-image inpainting)")
            assert noise is not None
            inpaint_extension = RectifiedFlowInpaintExtension(
                init_latents=init_latents,
                inpaint_mask=inpaint_mask,
                noise=noise,
            )

        step_callback = self._build_step_callback(context)

        # Initialize the diffusers scheduler if not using built-in Euler
        scheduler: SchedulerMixin | None = None
        use_scheduler = self.scheduler != "euler"

        if use_scheduler:
            scheduler_class = ZIMAGE_SCHEDULER_MAP[self.scheduler]
            scheduler = scheduler_class(
                num_train_timesteps=1000,
                shift=1.0,

View on GitHub (pinned to 0b6a024f2f)

Solutions

Connect an initial image (run through image-to-latents) to the denoise invocation when using an inpaint mask
Or remove/disconnect the inpaint mask if you intend pure txt2img generation
Validate the graph so mask connections imply a connected latents/image input

Example fix

// before
# mask connected, but no initial latents
latents = denoise.invoke(context)  # raises
// after
init_latents = image_to_latents.invoke(context)
latents = denoise_with_mask_and_init_latents.invoke(context)

Defensive patterns

Strategy: validation

Validate before calling

if mask_connected and initial_latents is None:
    raise ValueError("Inpaint mask requires initial latents (img2img inpainting)")

Try / catch

try:
    output = denoise.invoke(context)
except ValueError as e:
    if "Initial latents are required" in str(e):
        raise GraphConfigError("connect image-to-latents before masked denoise") from e
    raise

Prevention

Treat (mask, latents) as an inseparable pair in inpaint graphs
Validate graph edges before invoking
Remove mask connections from txt2img templates

When it happens

Trigger: Running the Z-Image denoise invocation where _prep_inpaint_mask returns a mask (mask input connected) but init_latents is None — i.e. mask present without initial image/latents.

Common situations: Connecting a mask to a txt2img graph by mistake; removing the image input while leaving the mask connected; forgetting to run image-to-latents before the denoise step in an inpaint workflow.

Related errors

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