Inpaint Canvas:
InpaintCanvas provides a layered painting workspace inside ComfyUI for making focused AI edits without repeatedly exporting images or manually pasting generated patches back into place. You open its full-window editor, load an image, and paint a selection over the area you want to change. The node prepares that area with surrounding visual context, lets your chosen inpainting workflow generate a replacement, and brings the replacement back as a new layer. During stitching, it resizes the generated patch to its original position and softens the transition into the surrounding image, helping localized edits blend naturally. The editor supports local generation and API-based editing workflows, along with reference images, control layers, prompts, and editor-driven generation settings. This makes it useful for iterative tasks such as replacing clothing, repairing details, changing objects, or refining a small part of a larger composition while keeping your work organized on a single canvas.
Inpaint Canvas Input Parameters:
padding
A required INT that controls how many pixels of surrounding context are included around your painted selection before the region is cropped. Extra context helps an editing model understand nearby colors, lighting, shapes, and objects rather than seeing only the area being replaced. Larger values include more surroundings but can make the selected subject occupy less of the generated image when the crop is resized; smaller values concentrate generation on the selected detail. This setting is ignored when the editor’s Context setting is set to auto, because the node calculates the context automatically. Default: 64; minimum: 0; maximum: 4096; interface step: 8. Padding is measured in the original canvas’s pixels, before any resizing for generation.
target_size
A required INT that sets the intended longest side of the image region sent for generation. A positive value scales the crop toward that size, allowing a small detail to be processed at a larger resolution or a large region to be reduced for a more manageable workload. The width and height are then rounded to satisfy multiple_of, so the final longest side can differ slightly from the requested value. Setting this to 0 skips this resizing step and keeps the crop at native resolution, although its boundaries may be expanded to satisfy the size-multiple requirement where the canvas permits. Default: 1024; minimum: 0; maximum: 8192; interface step: 8. Higher values can increase detail potential but also increase the processing demands of your connected generation chain.
feather
A required INT that sets the blur radius used to soften the selection boundary when a generated result is stitched back into the canvas. A larger value produces a wider, softer transition, which can help hide seams; a smaller value preserves a tighter boundary around the edit. Setting it to 0 removes this manually requested blur. This parameter is ignored when the editor’s Feather setting is auto, because the node calculates its own selection growth and blending behavior. In ordinary manual-feather operation, this value affects the stitched transition rather than blurring the outgoing selection mask. Default: 16; minimum: 0; maximum: 512; interface step: 1.
multiple_of
A required INT that controls the size increments used for the generated crop’s width and height. Many image models require dimensions that divide evenly by a particular number; the node’s tooltip specifically identifies 64 as suitable for Flux. With a positive target_size, each dimension is rounded to a multiple of this value, with at least one multiple used for each side. With target_size set to 0, the node instead attempts to expand the crop boundaries to compatible dimensions within the canvas. Default: 64; minimum: 1; maximum: 256; interface step: 1. Choose the value required by your connected model rather than changing it solely for visual reasons.
result
An optional IMAGE connection for the finished image from your API-based editing chain. Connect the generated image back here so the node can resize and blend the edited region into the canvas as a new layer. In API mode, this connection is preferred; if it is not connected, the node can use result_local instead. The connection is evaluated lazily, meaning the stitching process requests the selected result chain rather than automatically running both generation paths. Although this return connection appears to create a loop in the graph, the extension’s frontend handles it specially so the crop-generation-and-return workflow can execute.
result_local
An optional IMAGE connection for the decoded image from your local inpainting chain. For example, connect the image produced after decoding your sampler’s latent result, rather than connecting the latent data itself. In Local mode, this connection is preferred; if it is not connected, the node can fall back to result. Like result, it is evaluated lazily so that the selected generation path is the one requested for stitching. When both return connections are present, the editor’s mode determines which chain is used. No numeric range or default image is defined for either return connection.
Inpaint Canvas Output Parameters:
crop_image
An IMAGE containing the selected region and its surrounding context, resized according to your crop settings. This is the image you normally send into your inpainting or image-editing workflow. It can contain more than one image as a batch: when a fill mode and the editor’s Original option are enabled, the filled crop is followed by the untouched crop, and visible reference images are appended afterward, fitted to the crop dimensions. The untouched version gives compatible editing models access to content hidden by the fill, while reference images provide additional visual guidance. Your downstream nodes must support the resulting batch behavior; compatible Flux.2 or Kontext workflows can use these images as multiple image inputs.
crop_mask
A MASK that identifies the selected area within the cropped, resized image region. Higher values indicate selected areas and lower values indicate unselected areas; soft intermediate values describe transitions. Its spatial dimensions match the crop dimensions, making it suitable for the mask connection of an inpainting workflow. When the editor’s Feather setting is auto, the selection can be grown and softened before being sent to the generation chain. In manual-feather mode, the outgoing mask is based on the raw selection rather than the manual stitching blur. Local Refine mode removes growth and feathering from the generation mask so the sampler works on the plain selection.
image
An IMAGE representing the flattened canvas at its full resolution, rather than only the region selected for editing. This gives other parts of your workflow access to the complete current composition. It is useful for full-image previews, saving, or processing that needs the surrounding artwork rather than a cropped patch. The full-size canvas and the generated crop serve different purposes: this output represents the overall image, while crop_image is prepared specifically for the localized editing chain.
mask
A MASK representing the selection at the full canvas size. Unlike crop_mask, it remains in the coordinate space of the complete image, making it useful for full-resolution masking or compositing operations. Higher values identify the selected area, while lower values identify areas outside it. This output represents the canvas selection rather than the automatically grown and feathered generation mask prepared for the cropped workflow.
stitch_info
A STRING containing the information needed to place the generated crop back into the original image through a standalone Inpaint Canvas Stitch node. It carries placement and stitching settings associated with the crop, allowing the stitch operation to account for its original location, size, and blending behavior. Treat it as connection data rather than an artistic prompt or text that you normally edit manually. Use it when you want an explicit stitching stage instead of relying exclusively on the canvas’s automatic return workflow.
crop_width
An INT giving the actual width, in pixels, of crop_image after crop preparation and resizing. Connect it to generation nodes that require an explicit image width. Because the node applies size-multiple rounding, this is more reliable than assuming the width from target_size alone. It describes each image’s spatial width, not the number of images in a batch.
crop_height
An INT giving the actual height, in pixels, of crop_image after crop preparation and resizing. Connect it to generation nodes that require an explicit image height so their output matches the prepared editing region. Together with crop_width, it describes the crop’s final dimensions, including adjustments made to satisfy multiple_of.
prompt
A STRING containing the prompt entered in the canvas editor. Connect it to a compatible text-conditioning or editing-model prompt input so you can describe the desired change without leaving the editor. This is the ordinary editor prompt; workflows using the specialized FLUX 3 box instructions should use box_prompt when those structured editing instructions are needed.
control_image
An IMAGE containing the editor’s control-layer content, such as scribble, line art, depth, or pose guidance, on a black background. It is cropped and resized using the same region and dimensions as crop_image, keeping the guidance spatially aligned with the generated edit. Connect it to the appropriate ControlNet or compatible guidance workflow for the type of control content you created. When no control image is available, the node produces a black image rather than automatically deriving guidance from the main canvas.
denoise
A FLOAT containing the denoise strength from the editor’s Generate section, constrained to the range 0.0–1.0. Connect it to your local sampler to control how strongly generation can alter the existing content; the node describes 1.0 as a full repaint. Lower values are useful for more restrained changes, although the exact visual effect depends on your sampler and model. In Local mode, the node also uses this strength when calculating automatic selection settings. The editor value defaults to 1.0 when it is absent; API-mode automatic selection calculations use full strength instead.
seed
An INT containing the seed provided by the editor. The editor supports a fixed seed or a seed randomized per run, and this output lets you pass that choice to a local sampler. A fixed seed helps you compare prompt or setting changes while keeping the starting randomness consistent. A randomized seed encourages variation between runs. The execution code uses 0 if no seed value is present.
mode
A STRING containing either api or local, reflecting the editor’s selected generation mode. It identifies which return connection the node prefers when retrieving an edited image. If the preferred connection is missing, the node can use the other connected return path, so this value describes the selected mode rather than guaranteeing that a particular return connection was used. When the editor does not explicitly select Local mode, the execution code uses API mode.
negative
A STRING containing the negative prompt entered in the editor. The editor shows this control in Local mode for workflows such as SDXL-class models that use negative conditioning. Connect it to the appropriate negative-text conditioning path if your model supports one. It communicates what you want the model to avoid; it does not automatically apply negative conditioning unless you connect it into your generation workflow.
setting_1
A wildcard output, shown as *, for exposing a connected generation setting inside the editor. Connect it to a compatible widget input, such as lora_name, ckpt_name, or steps, and the editor displays a matching control. Its meaning and usable values come from the connected destination rather than a fixed InpaintCanvas parameter definition. Connecting this slot makes the next available setting slot appear, allowing you to build a small set of editor-accessible controls.
setting_2
A wildcard output for a second editor-driven setting. Like setting_1, it takes its practical role from the widget input you connect it to, so it can represent a model choice, a sampling setting, or another supported control. Its value is whatever you select through the corresponding editor control; no independent numeric range or default is specified by InpaintCanvas for this slot.
setting_3
A wildcard output for a third editor-driven setting. Use it to bring another supported downstream widget into the canvas editor so you can adjust that part of your workflow alongside your selection and prompt. The connected widget determines the expected value type, available options, and valid range rather than the slot having a predefined purpose.
setting_4
A wildcard output for a fourth editor-driven setting. It lets you expose another connected widget as an editor control, reducing the need to return to the node graph during repeated edits. Its output should be interpreted according to its destination, such as a filename choice or a numeric generation setting; InpaintCanvas does not assign this slot a fixed default or range.
setting_5
A wildcard output for a fifth editor-driven setting. Connect it to a supported widget input to control that setting from the canvas editor. The destination defines what the value means and which values are accepted, so this slot is not inherently associated with any particular sampler, model, or artistic effect.
setting_6
A wildcard output for a sixth editor-driven setting. It provides another customizable bridge between the editor and a downstream widget. Use it when your workflow needs more editor-accessible controls beyond the earlier slots, with the connected input determining its data type, options, and impact on generation.
setting_7
A wildcard output for a seventh editor-driven setting. It carries the value of the editor control associated with its connected widget input. As with the other setting slots, its purpose is defined by your wiring, and its allowed values should be understood from the receiving node rather than from a fixed range in InpaintCanvas.
setting_8
A wildcard output for an eighth editor-driven setting, completing the eight available setting slots. It works in the same way as the earlier slots: connect a supported widget input to expose a matching control in the editor. There is no universal default, minimum, maximum, or option list for this output because those details depend on the destination you choose.
box_prompt
A STRING containing the editor prompt together with FLUX 3 box instructions when the editor’s Boxes switch is enabled. Boxes drawn with tool X are represented as a caption and structured JSON rows for operations such as New, Keep, Move, Remove, and From a reference. Connect this to a FLUX 3 node’s prompt input and send the complete crop_image output to its first image input. With Boxes disabled, this output is the plain prompt; with Boxes enabled but no box drawn, the selection is sent as one box. It is intended for structured editing instructions rather than ordinary negative conditioning.
elements
An ARRAY containing New and Text boxes represented as bounding-box elements. It is intended for workflows such as Flux 3 Image’s bounding_boxes input on a new image, Create Bounding Boxes, or a compatible JSON prompt builder. These elements describe placement instructions rather than image pixels. For an edit workflow, use box_prompt instead; supplying both representations to the same operation can duplicate the box rows.
Inpaint Canvas Usage Tips:
- Load your starting image in the canvas editor before running the workflow, then paint a clear selection over the area you want to change. The node cannot prepare an editing region without a loaded base image.
- For a basic local workflow, send
crop_imageandcrop_maskinto an appropriate inpainting chain, decode the generated result, and connect that IMAGE toresult_local. Connect the editor’sprompt,denoise, andseedto the corresponding parts of your workflow if you want those editor controls to drive generation. - For an API editing workflow, send the prepared crop and prompt to a compatible image-editing node and return its IMAGE through
result. Select API mode in the editor; if both local and API chains are connected, the selected mode determines which return path is requested. - Start with automatic Context and Feather when you want the node to calculate selection-dependent settings. If changes to
paddingorfeatherappear to do nothing, switch the corresponding editor setting away from auto before adjusting the numeric value. - Use
target_sizeto balance editing resolution against processing cost. The default 1024 is a starting point, not a requirement for every model; check your model’s size limits, especially before selecting very large crops or high target sizes. - For small details, processing an enlarged crop can give the model more working resolution without regenerating the entire canvas. Include enough context to communicate the surrounding shape and lighting, but avoid so much padding that the selected detail becomes tiny within the crop.
- Set
multiple_ofto the dimension requirement of your generation model. Usecrop_widthandcrop_heightwherever your chain asks for explicit dimensions instead of manually entering sizes that might disagree with the prepared crop. - Increase manual
featherwhen a patch has a visibly hard boundary, and reduce it when blending spreads too far into neighboring details. A mismatch in lighting or content may also need a better prompt or more context; edge softness alone cannot correct every seam. - Try Local Refine mode for a refinement pass that should see the untouched crop and plain selection. In this mode, the node disables filling and generation-mask growth while retaining a soft compositing transition.
- Enable the Original option with a fill mode when a compatible editing model needs both the obscured region and the original content. Remember that this produces an image batch, and adding reference layers expands that batch further.
- Use
control_imagewith a guidance chain suited to the content of your control layers. A pose drawing, depth image, and line-art image are different kinds of guidance and should not be treated as interchangeable. - Expose frequently adjusted widgets through
setting_1throughsetting_8. For example, placing a supported steps or LoRA selection control in the editor can make repeated localized edits more convenient. - For FLUX 3 edits, use
box_prompt; for supported new-image bounding-box workflows, useelements. Avoid feeding both into a workflow that would interpret them as duplicate box instructions.
Inpaint Canvas Common Errors and Solutions:
Inpaint Canvas: load an image into the canvas first.
- Explanation: This is an explicit error raised when the editor state does not contain a base image. The node needs that image to determine the canvas dimensions and prepare the selected crop.
- Solution: Open the editor, load your starting image, confirm that it appears on the canvas, and run the workflow again.
Inpaint Canvas: reference 1 (@img1) could not be loaded (...)
- Explanation: This is the beginning of an explicit error whose reference number and detailed reason vary. When the prompt names references by their batch positions, the node stops if a required reference cannot be loaded, because skipping it could make the prompt refer to the wrong image.
- Solution: Replace or hide the reference identified in the message, check that its image file is available, and review the prompt’s reference names before running again. The full message includes the underlying loading problem.
[Inpaint Canvas] reference skipped: ...
- Explanation: This is a console warning rather than necessarily a failed run. When references are not explicitly named by batch position, a reference that raises a loading error can be skipped while the rest of the workflow continues. The result may therefore lack guidance you expected.
- Solution: Check the referenced image’s availability and replace or reload the affected reference layer. If its visual guidance is important, verify that it is present before generating another result.
Symptom: the result connection is reported as a cycle
- Explanation: The crop-to-generator-to-canvas return connection looks circular to ordinary graph execution. The extension is designed to handle this through its frontend, which removes the return link from the submitted prompt and supplies its source for a separate stitching step. A cycle error suggests that this special handling may not be active.
- Solution: Confirm that the custom node and its frontend extension are installed and loaded, restart ComfyUI, and refresh the browser. If you are submitting workflows outside the editor frontend, do not assume ordinary circular connections will receive the same handling; consider an explicit standalone stitching workflow.
Symptom: padding or feather changes have no visible effect
- Explanation: The editor’s automatic settings override the corresponding numeric controls. In addition, manual
feathernormally affects stitching rather than the outgoingcrop_mask, so inspecting only that mask can make the control appear inactive. - Solution: Disable automatic Context to test
padding, or disable automatic Feather to testfeather. Evaluate feathering on the stitched result rather than expecting the manual value to soften the outgoing mask.
Symptom: the wrong generation chain runs, or a return image is not used
- Explanation: The node prefers
resultin API mode andresult_localin Local mode. If the preferred connection is absent, it falls back to the other one. Only the selected return path is requested, so connecting both paths does not mean both will run. - Solution: Check the editor’s mode and verify that each chain returns to the intended input. For local generation, ensure the returned data is a decoded IMAGE rather than a latent representation.
Symptom: the connected model rejects the crop dimensions
- Explanation: Different models can impose different dimension requirements. An incompatible
multiple_ofsetting, or a native-size crop constrained by the canvas boundaries, can leave dimensions unsuitable for your downstream chain. - Solution: Check the model’s requirements, set an appropriate
multiple_of, and inspectcrop_widthandcrop_height. Try a positivetarget_sizeso the crop is resized to compatible multiples, and connect the emitted dimensions to nodes that require explicit sizes.
Symptom: an editing node receives unexpected extra images
- Explanation:
crop_imagebecomes a batch when the untouched Original crop is included with a fill mode or when reference images are present. A downstream node that expects one image may process that batch differently from a multi-reference editing node. - Solution: Disable the Original option and hide unnecessary reference layers for a single-image workflow, or use a downstream chain that explicitly supports the batch and reference arrangement.
Symptom: box instructions appear twice
- Explanation: The node’s interface specifically warns that using both
box_promptandelementsfor an edit can supply the same box rows twice. - Solution: Use
box_promptfor the structured editing prompt, or useelementsin the supported new-image bounding-box workflow. Avoid sending both representations into the same instruction-building path.
Symptom: generation runs out of memory or becomes unusually slow
- Explanation: This is a possible downstream processing issue rather than a specific InpaintCanvas error string. A large
target_sizeincreases image dimensions, and Original or reference images increase the number of images sent for processing. - Solution: Lower
target_sizeto a resolution supported comfortably by your model and hardware, remove unnecessary references, and disable Original when it is not needed. Check the connected model or API’s resolution and image-count limits as well.
