{"record":{"id":"86b1d2544efbd3c8","repo":"Comfy-Org/ComfyUI","slug":"custom-resolution-total-pixels-must-be-between-655","errorCode":null,"errorMessage":"Custom resolution total pixels must be between 655,360 and 8,294,400, got {total_pixels}","messagePattern":"Custom resolution total pixels must be between 655,360 and 8,294,400, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/nodes_openai.py","lineNumber":552,"sourceCode":"\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                )\n            size = f\"{custom_width}x{custom_height}\"\n        elif model in (\"gpt-image-1\", \"gpt-image-1.5\"):\n            if size not in (\"auto\", \"1024x1024\", \"1024x1536\", \"1536x1024\"):\n                raise ValueError(f\"Resolution {size} is only supported by GPT Image 2 model\")\n\n        if model == \"gpt-image-2\":\n            if background == \"transparent\":\n                raise ValueError(\"Transparent background is not supported for GPT Image 2 model\")\n        elif model not in (\"gpt-image-1\", \"gpt-image-1.5\"):\n            raise ValueError(f\"Unknown model: {model}\")\n\n        if image is not None:\n            files = []\n            batch_size = image.shape[0]\n            for i in range(batch_size):\n                single_image = image[i : i + 1]","sourceCodeStart":534,"sourceCodeEnd":570,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/nodes_openai.py#L534-L570","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before\ncustom_width, custom_height = 512, 512   # 262,144 px, raises\n// after\ncustom_width, custom_height = 1024, 640  # 655,360 px, minimum allowed","handlingStrategy":"validation","validationCode":"px = custom_width * custom_height\nassert 655_360 <= px <= 8_294_400, f\"total pixels {px} out of range\"","typeGuard":"def within_pixel_budget(w: int, h: int) -> bool:\n    return 655_360 <= w * h <= 8_294_400","tryCatchPattern":null,"preventionTips":["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"],"tags":["openai","gpt-image","resolution","validation","limits"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}