{"record":{"id":"7693d54ddb4ca3f5","repo":"Comfy-Org/ComfyUI","slug":"cannot-use-a-mask-without-an-input-image","errorCode":null,"errorMessage":"Cannot use a mask without an input image","messagePattern":"Cannot use a mask without an input image","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/nodes_openai.py","lineNumber":536,"sourceCode":"    @classmethod\n    async def execute(\n        cls,\n        prompt: str,\n        seed: int = 0,\n        quality: str = \"low\",\n        background: str = \"opaque\",\n        image: Input.Image | None = None,\n        mask: Input.Image | None = None,\n        n: int = 1,\n        size: str = \"1024x1024\",\n        custom_width: int = 1024,\n        custom_height: int = 1024,\n        model: str = \"gpt-image-1\",\n    ) -> IO.NodeOutput:\n        validate_string(prompt, strip_whitespace=False)\n\n        if mask is not None and image is None:\n            raise ValueError(\"Cannot use a mask without an input image\")\n\n        if size == \"Custom\":\n            if model != \"gpt-image-2\":\n                raise ValueError(\"Custom resolution is only supported by GPT Image 2 model\")\n            if custom_width % 16 != 0 or custom_height % 16 != 0:\n                raise ValueError(f\"Custom width and height must be multiples of 16, got {custom_width}x{custom_height}\")\n            if max(custom_width, custom_height) > 3840:\n                raise ValueError(f\"Custom resolution max edge must be <= 3840, got {custom_width}x{custom_height}\")\n            ratio = max(custom_width, custom_height) / min(custom_width, custom_height)\n            if ratio > 3:\n                raise ValueError(\n                    f\"Custom resolution aspect ratio must not exceed 3:1, got {custom_width}x{custom_height}\"\n                )\n            total_pixels = custom_width * custom_height\n            if not 655_360 <= total_pixels <= 8_294_400:\n                raise ValueError(\n                    f\"Custom resolution total pixels must be between 655,360 and 8,294,400, got {total_pixels}\"\n                )","sourceCodeStart":518,"sourceCodeEnd":554,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/nodes_openai.py#L518-L554","documentation":"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).","triggerScenarios":"Invoking the OpenAIImage generate/edit node with mask != None and image == None.","commonSituations":"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.","solutions":["Connect an input image, or disconnect the mask","If the intent is text-to-image with a shape guide, use an image input that encodes the guide instead of a mask","Audit workflow links after removing inputs so mask/image stay paired"],"exampleFix":"// before\nnode(prompt=\"...\", mask=mask_tensor)  # image left unconnected\n// after\nnode(prompt=\"...\", image=base_image, mask=mask_tensor)","handlingStrategy":"validation","validationCode":"if mask is not None and image is None:\n    mask = None  # or connect an image before running","typeGuard":"def mask_usable(image, mask) -> bool:\n    return mask is None or image is not None","tryCatchPattern":null,"preventionTips":["Treat mask as a modifier of image: no image, no mask","Build workflows so the image branch is always populated before the mask branch","Disconnect both when switching to pure generation"],"tags":["openai","gpt-image","mask","validation"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}