What causes "Cannot use a mask with multiple image" in Comfy-Org/ComfyUI?

Reduce the image input to a single image (batch size 1) before attaching the mask, e.g. slice image[0:1]

Comfy-Org/ComfyUI · error · Exception

Cannot use a mask with multiple image

Error message

Cannot use a mask with multiple image

What it means

Exception raised in the gpt-image edit path when a mask is supplied together with a batched image input (image.shape[0] != 1). The multipart API contract allows at most one mask, which can only correspond to a single image, so multi-image batches plus a mask are rejected.

Source

Thrown at comfy_api_nodes/nodes_openai.py:586

            batch_size = image.shape[0]
            for i in range(batch_size):
                single_image = image[i : i + 1]
                scaled_image = downscale_image_tensor(single_image, total_pixels=2048 * 2048).squeeze()

                image_np = (scaled_image.numpy() * 255).astype(np.uint8)
                img = Image.fromarray(image_np)
                img_byte_arr = BytesIO()
                img.save(img_byte_arr, format="PNG")
                img_byte_arr.seek(0)

                if batch_size == 1:
                    files.append(("image", (f"image_{i}.png", img_byte_arr, "image/png")))
                else:
                    files.append(("image[]", (f"image_{i}.png", img_byte_arr, "image/png")))

            if mask is not None:
                if image.shape[0] != 1:
                    raise Exception("Cannot use a mask with multiple image")
                if mask.shape[1:] != image.shape[1:-1]:
                    raise Exception("Mask and Image must be the same size")
                _, height, width = mask.shape
                rgba_mask = torch.zeros(height, width, 4, device="cpu")
                rgba_mask[:, :, 3] = 1 - mask.squeeze().cpu()

                scaled_mask = downscale_image_tensor(rgba_mask.unsqueeze(0), total_pixels=2048 * 2048).squeeze()

                mask_np = (scaled_mask.numpy() * 255).astype(np.uint8)
                mask_img = Image.fromarray(mask_np)
                mask_img_byte_arr = BytesIO()
                mask_img.save(mask_img_byte_arr, format="PNG")
                mask_img_byte_arr.seek(0)
                files.append(("mask", ("mask.png", mask_img_byte_arr, "image/png")))

            response = await sync_op(
                cls,
                ApiEndpoint(path="/proxy/openai/images/edits", method="POST"),

View on GitHub (pinned to 1c6d8d45b3)

Solutions

Reduce the image input to a single image (batch size 1) before attaching the mask, e.g. slice image[0:1]
Drop the mask if you genuinely want to edit the whole batch
Loop the node once per image (each with its own mask) instead of batching

Example fix

// before
image  # shape (4, H, W, 3)
node(image=image, mask=mask)
// after
image = image[0:1]  # single image
node(image=image, mask=mask)

Defensive patterns

Strategy: validation

Validate before calling

if mask is not None:
    assert image.shape[0] == 1, "mask requires a single-image (batch size 1) input"

Type guard

def mask_compatible_with_batch(mask, image) -> bool:
    return mask is None or image.shape[0] == 1

Prevention

Slice batches to image[0:1] before attaching a mask
Check tensor.shape[0] on image inputs from batch-producing nodes
Loop per-image with per-image masks instead of batching masked edits

When it happens

Trigger: Connecting an image tensor with batch size > 1 (e.g. a 4-frame batch or image list) together with a mask input on the gpt-image node.

Common situations: Feeding the output of a node that emits image batches; LoadImage with a multi-page file; iterating a workflow where the image input unexpectedly carries N>1 images.

Related errors

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/24a51e1902e14d24. Report an issue: GitHub.