{"record":{"id":"b0adc981185b079b","repo":"invoke-ai/InvokeAI","slug":"initial-latents-are-required-when-using-an-inpaint-b0adc9","errorCode":null,"errorMessage":"Initial latents are required when using an inpaint mask (image-to-image inpainting)","messagePattern":"Initial latents are required when using an inpaint mask \\(image-to-image inpainting\\)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/app/invocations/z_image_denoise.py","lineNumber":395,"sourceCode":"                latents = s_0 * noise + (1.0 - s_0) * init_latents\n            else:\n                latents = init_latents\n        else:\n            if self.denoising_start > 1e-5:\n                raise ValueError(\"denoising_start should be 0 when initial latents are not provided.\")\n            assert noise is not None\n            latents = noise\n\n        # Short-circuit if no denoising steps\n        if total_steps <= 0:\n            return latents\n\n        # Prepare inpaint extension\n        inpaint_mask = self._prep_inpaint_mask(context, latents)\n        inpaint_extension: RectifiedFlowInpaintExtension | None = None\n        if inpaint_mask is not None:\n            if init_latents is None:\n                raise ValueError(\"Initial latents are required when using an inpaint mask (image-to-image inpainting)\")\n            assert noise is not None\n            inpaint_extension = RectifiedFlowInpaintExtension(\n                init_latents=init_latents,\n                inpaint_mask=inpaint_mask,\n                noise=noise,\n            )\n\n        step_callback = self._build_step_callback(context)\n\n        # Initialize the diffusers scheduler if not using built-in Euler\n        scheduler: SchedulerMixin | None = None\n        use_scheduler = self.scheduler != \"euler\"\n\n        if use_scheduler:\n            scheduler_class = ZIMAGE_SCHEDULER_MAP[self.scheduler]\n            scheduler = scheduler_class(\n                num_train_timesteps=1000,\n                shift=1.0,","sourceCodeStart":377,"sourceCodeEnd":413,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/app/invocations/z_image_denoise.py#L377-L413","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\n# mask connected, but no initial latents\nlatents = denoise.invoke(context)  # raises\n// after\ninit_latents = image_to_latents.invoke(context)\nlatents = denoise_with_mask_and_init_latents.invoke(context)","handlingStrategy":"validation","validationCode":"if mask_connected and initial_latents is None:\n    raise ValueError(\"Inpaint mask requires initial latents (img2img inpainting)\")","typeGuard":null,"tryCatchPattern":"try:\n    output = denoise.invoke(context)\nexcept ValueError as e:\n    if \"Initial latents are required\" in str(e):\n        raise GraphConfigError(\"connect image-to-latents before masked denoise\") from e\n    raise","preventionTips":["Treat (mask, latents) as an inseparable pair in inpaint graphs","Validate graph edges before invoking","Remove mask connections from txt2img templates"],"tags":["inpainting","diffusion","validation"],"backgroundTag":"missing-required-input","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}