Comfy-Org/ComfyUI · error · ValueError

Cannot use a mask without an input image

Error message

Cannot use a mask without an input image

What it means

Client-side ValueError from the OpenAI image node when a mask is connected but no input image is supplied. Masks select the region of an image to edit, so a mask without an image has no referent; the node rejects the combination before any upload. Mirrors the same rule enforced in the dict-driven path (line ~839).

Source

Thrown at comfy_api_nodes/nodes_openai.py:536

    @classmethod
    async def execute(
        cls,
        prompt: str,
        seed: int = 0,
        quality: str = "low",
        background: str = "opaque",
        image: Input.Image | None = None,
        mask: Input.Image | None = None,
        n: int = 1,
        size: str = "1024x1024",
        custom_width: int = 1024,
        custom_height: int = 1024,
        model: str = "gpt-image-1",
    ) -> IO.NodeOutput:
        validate_string(prompt, strip_whitespace=False)

        if mask is not None and image is None:
            raise ValueError("Cannot use a mask without an input image")

        if size == "Custom":
            if model != "gpt-image-2":
                raise ValueError("Custom resolution is only supported by GPT Image 2 model")
            if custom_width % 16 != 0 or custom_height % 16 != 0:
                raise ValueError(f"Custom width and height must be multiples of 16, got {custom_width}x{custom_height}")
            if max(custom_width, custom_height) > 3840:
                raise ValueError(f"Custom resolution max edge must be <= 3840, got {custom_width}x{custom_height}")
            ratio = max(custom_width, custom_height) / min(custom_width, custom_height)
            if ratio > 3:
                raise ValueError(
                    f"Custom resolution aspect ratio must not exceed 3:1, got {custom_width}x{custom_height}"
                )
            total_pixels = custom_width * custom_height
            if not 655_360 <= total_pixels <= 8_294_400:
                raise ValueError(
                    f"Custom resolution total pixels must be between 655,360 and 8,294,400, got {total_pixels}"
                )

View on GitHub (pinned to 1c6d8d45b3)

Solutions

  1. Connect an input image, or disconnect the mask
  2. If the intent is text-to-image with a shape guide, use an image input that encodes the guide instead of a mask
  3. Audit workflow links after removing inputs so mask/image stay paired

Example fix

// before
node(prompt="...", mask=mask_tensor)  # image left unconnected
// after
node(prompt="...", image=base_image, mask=mask_tensor)
Defensive patterns

Strategy: validation

Validate before calling

if mask is not None and image is None:
    mask = None  # or connect an image before running

Type guard

def mask_usable(image, mask) -> bool:
    return mask is None or image is not None

Prevention

When it happens

Trigger: Invoking the OpenAIImage generate/edit node with mask != None and image == None.

Common situations: Leftover mask wiring after removing the image input; building a workflow where the mask branch is populated conditionally and the image branch is not; converting an img2img workflow and forgetting the source image.

Related errors

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