{"record":{"id":"24a51e1902e14d24","repo":"Comfy-Org/ComfyUI","slug":"cannot-use-a-mask-with-multiple-image","errorCode":null,"errorMessage":"Cannot use a mask with multiple image","messagePattern":"Cannot use a mask with multiple image","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/nodes_openai.py","lineNumber":586,"sourceCode":"            batch_size = image.shape[0]\n            for i in range(batch_size):\n                single_image = image[i : i + 1]\n                scaled_image = downscale_image_tensor(single_image, total_pixels=2048 * 2048).squeeze()\n\n                image_np = (scaled_image.numpy() * 255).astype(np.uint8)\n                img = Image.fromarray(image_np)\n                img_byte_arr = BytesIO()\n                img.save(img_byte_arr, format=\"PNG\")\n                img_byte_arr.seek(0)\n\n                if batch_size == 1:\n                    files.append((\"image\", (f\"image_{i}.png\", img_byte_arr, \"image/png\")))\n                else:\n                    files.append((\"image[]\", (f\"image_{i}.png\", img_byte_arr, \"image/png\")))\n\n            if mask is not None:\n                if image.shape[0] != 1:\n                    raise Exception(\"Cannot use a mask with multiple image\")\n                if mask.shape[1:] != image.shape[1:-1]:\n                    raise Exception(\"Mask and Image must be the same size\")\n                _, height, width = mask.shape\n                rgba_mask = torch.zeros(height, width, 4, device=\"cpu\")\n                rgba_mask[:, :, 3] = 1 - mask.squeeze().cpu()\n\n                scaled_mask = downscale_image_tensor(rgba_mask.unsqueeze(0), total_pixels=2048 * 2048).squeeze()\n\n                mask_np = (scaled_mask.numpy() * 255).astype(np.uint8)\n                mask_img = Image.fromarray(mask_np)\n                mask_img_byte_arr = BytesIO()\n                mask_img.save(mask_img_byte_arr, format=\"PNG\")\n                mask_img_byte_arr.seek(0)\n                files.append((\"mask\", (\"mask.png\", mask_img_byte_arr, \"image/png\")))\n\n            response = await sync_op(\n                cls,\n                ApiEndpoint(path=\"/proxy/openai/images/edits\", method=\"POST\"),","sourceCodeStart":568,"sourceCodeEnd":604,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/nodes_openai.py#L568-L604","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nimage  # shape (4, H, W, 3)\nnode(image=image, mask=mask)\n// after\nimage = image[0:1]  # single image\nnode(image=image, mask=mask)","handlingStrategy":"validation","validationCode":"if mask is not None:\n    assert image.shape[0] == 1, \"mask requires a single-image (batch size 1) input\"","typeGuard":"def mask_compatible_with_batch(mask, image) -> bool:\n    return mask is None or image.shape[0] == 1","tryCatchPattern":null,"preventionTips":["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"],"tags":["openai","gpt-image","mask","batching","validation"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}