{"record":{"id":"82a69262c7453421","repo":"Comfy-Org/ComfyUI","slug":"custom-resolution-aspect-ratio-must-not-exceed-3-1","errorCode":null,"errorMessage":"Custom resolution aspect ratio must not exceed 3:1, got {custom_width}x{custom_height}","messagePattern":"Custom resolution aspect ratio must not exceed 3:1, got (.+?)x(.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/nodes_openai.py","lineNumber":547,"sourceCode":"        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                )\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","sourceCodeStart":529,"sourceCodeEnd":565,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/nodes_openai.py#L529-L565","documentation":"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.","triggerScenarios":"size='Custom' with extreme panoramas such as 3840x960 (4:1), 3072x768 (4:1), or 1920x512 (3.75:1).","commonSituations":"Wide banner or cinematic strip generation; letterbox-format requests; height shrunk to meet the pixel budget while width stays large.","solutions":["Bring the ratio within 3:1 (e.g. 3072x1024 is exactly 3:1 and passes)","Crop or pad the generated image locally to reach the extreme ratio you want","If a wide strip is essential, tile multiple generations and stitch"],"exampleFix":"// before\ncustom_width, custom_height = 3840, 960  # 4:1, raises\n// after\ncustom_width, custom_height = 2880, 960  # exactly 3:1, passes","handlingStrategy":"validation","validationCode":"ratio = max(custom_width, custom_height) / min(custom_width, custom_height)\nassert ratio <= 3.0, f\"aspect ratio {ratio:.2f} exceeds 3:1\"","typeGuard":"def within_aspect_ratio(w: int, h: int, limit: float = 3.0) -> bool:\n    return max(w, h) / min(w, h) <= limit","tryCatchPattern":null,"preventionTips":["Compute long/short ratio before submitting Custom sizes","For panoramas, generate at 3:1 and crop/pad in post","Watch for ratios that drift past 3 when shrinking one dimension"],"tags":["openai","gpt-image","resolution","aspect-ratio","validation"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}