Comfy-Org/ComfyUI · error · ValueError

Custom resolution aspect ratio must not exceed 3:1, got {cus

Error message

Custom resolution aspect ratio must not exceed 3:1, got {custom_width}x{custom_height}

What it means

Client-side ValueError: the Custom resolution's aspect ratio (long edge / short edge) exceeds 3:1. GPT Image 2 only supports aspect ratios up to 3:1, and the node computes ratio = max/min and rejects values above 3 before the total-pixel check.

Source

Thrown at comfy_api_nodes/nodes_openai.py:547

        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")

        if model == "gpt-image-2":
            if background == "transparent":
                raise ValueError("Transparent background is not supported for GPT Image 2 model")
        elif model not in ("gpt-image-1", "gpt-image-1.5"):
            raise ValueError(f"Unknown model: {model}")

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Bring the ratio within 3:1 (e.g. 3072x1024 is exactly 3:1 and passes)
2. Crop or pad the generated image locally to reach the extreme ratio you want
3. If a wide strip is essential, tile multiple generations and stitch

Example fix

// before
custom_width, custom_height = 3840, 960  # 4:1, raises
// after
custom_width, custom_height = 2880, 960  # exactly 3:1, passes

ratio = max(custom_width, custom_height) / min(custom_width, custom_height)
assert ratio <= 3.0, f"aspect ratio {ratio:.2f} exceeds 3:1"

def within_aspect_ratio(w: int, h: int, limit: float = 3.0) -> bool:
    return max(w, h) / min(w, h) <= limit

When it happens

Trigger: size='Custom' with extreme panoramas such as 3840x960 (4:1), 3072x768 (4:1), or 1920x512 (3.75:1).

Common situations: Wide banner or cinematic strip generation; letterbox-format requests; height shrunk to meet the pixel budget while width stays large.

Related errors

• Custom resolution is only supported by GPT Image 2 model
• Custom width and height must be multiples of 16, got {custom
• Custom resolution max edge must be <= 3840, got {custom_widt
• Custom resolution total pixels must be between 655,360 and 8
• Resolution {size} is only supported by GPT Image 2 model

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