Comfy-Org/ComfyUI · error · ValueError

Custom resolution is only supported by GPT Image 2 model

Error message

Custom resolution is only supported by GPT Image 2 model

What it means

Client-side ValueError from the OpenAI image node: the size selector is set to 'Custom' but the chosen model is not gpt-image-2. Only GPT Image 2 accepts arbitrary custom_width/custom_height; gpt-image-1/1.5 are restricted to fixed sizes, so the node refuses the combination before the request.

Source

Thrown at comfy_api_nodes/nodes_openai.py:540

        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}"
                )
            size = f"{custom_width}x{custom_height}"
        elif model in ("gpt-image-1", "gpt-image-1.5"):
            if size not in ("auto", "1024x1024", "1024x1536", "1536x1024"):
                raise ValueError(f"Resolution {size} is only supported by GPT Image 2 model")

View on GitHub (pinned to 1c6d8d45b3)

Solutions

  1. Switch the model input to gpt-image-2 to use Custom resolution
  2. Or pick one of the preset sizes (auto/1024x1024/1024x1536/1536x1024) for gpt-image-1/1.5
  3. Fix stale workflow JSON so size and model widgets are consistent

Example fix

// before
model="gpt-image-1", size="Custom", custom_width=1280, custom_height=768
// after
model="gpt-image-2", size="Custom", custom_width=1280, custom_height=768
Defensive patterns

Strategy: validation

Validate before calling

if size == "Custom":
    assert model == "gpt-image-2", "Custom size requires gpt-image-2"

Type guard

def supports_custom_size(model: str) -> bool:
    return model == "gpt-image-2"

Prevention

When it happens

Trigger: Setting size='Custom' with model='gpt-image-1' or 'gpt-image-1.5' (the default model is gpt-image-1, so merely switching size to Custom triggers it).

Common situations: Default model left unchanged while the user picks Custom resolution; workflows built for gpt-image-2 run after the model dropdown was switched back; stale saved workflows after a model rename.

Related errors

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