Comfy-Org/ComfyUI · error · ValueError

Custom resolution total pixels must be between 655,360 and 8

Error message

Custom resolution total pixels must be between 655,360 and 8,294,400, got {total_pixels}

What it means

Client-side ValueError: the Custom resolution's total pixel count (width*height) is outside the allowed 655,360-8,294,400 range (roughly a 1024x640 minimum and a 3840x2160 maximum). The node enforces both floor and ceiling so the request stays within GPT Image 2's supported area.

Source

Thrown at comfy_api_nodes/nodes_openai.py:552

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

        if image is not None:
            files = []
            batch_size = image.shape[0]
            for i in range(batch_size):
                single_image = image[i : i + 1]

View on GitHub (pinned to 1c6d8d45b3)

Solutions

Choose dimensions whose product lies in [655360, 8294400] - e.g. 1024x768 up to 3840x2048
Scale down the long edge when both dimensions are large (3840x2160 is exactly at the 8,294,400 ceiling and passes)
For small outputs, generate at >= 655,360 pixels and downscale locally

Example fix

// before
custom_width, custom_height = 512, 512   # 262,144 px, raises
// after
custom_width, custom_height = 1024, 640  # 655,360 px, minimum allowed

Defensive patterns

Strategy: validation

Validate before calling

px = custom_width * custom_height
assert 655_360 <= px <= 8_294_400, f"total pixels {px} out of range"

Type guard

def within_pixel_budget(w: int, h: int) -> bool:
    return 655_360 <= w * h <= 8_294_400

Prevention

Avoid tiny test sizes like 512x512 - use presets for small outputs
Avoid maxing both edges at once (3840x2160 is the exact ceiling)
Check width*height whenever either dimension changes

When it happens

Trigger: size='Custom' with very small canvases (e.g. 512x512 = 262,144 pixels) or sizes at the extreme edge (e.g. 3840x2304 = 8,847,360 pixels).

Common situations: Testing with small fast sizes like 512x512; pushing both dimensions near the 3840 cap simultaneously; thin strips that pass the 3:1 check but fall under the pixel floor.

Related errors

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