{"record":{"id":"020be65c25c89fea","repo":"Comfy-Org/ComfyUI","slug":"image-width-must-be-at-most-max-width-px-got-wi","errorCode":null,"errorMessage":"Image width must be at most {max_width}px, got {width}px","messagePattern":"Image width must be at most (.+?)px, got (.+?)px","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/util/validation_utils.py","lineNumber":29,"sourceCode":"    elif len(image.shape) == 3:\n        return image.shape[0], image.shape[1]\n    else:\n        raise ValueError(\"Invalid image tensor shape.\")\n\n\ndef validate_image_dimensions(\n    image: torch.Tensor,\n    min_width: int | None = None,\n    max_width: int | None = None,\n    min_height: int | None = None,\n    max_height: int | None = None,\n):\n    height, width = get_image_dimensions(image)\n\n    if min_width is not None and width < min_width:\n        raise ValueError(f\"Image width must be at least {min_width}px, got {width}px\")\n    if max_width is not None and width > max_width:\n        raise ValueError(f\"Image width must be at most {max_width}px, got {width}px\")\n    if min_height is not None and height < min_height:\n        raise ValueError(f\"Image height must be at least {min_height}px, got {height}px\")\n    if max_height is not None and height > max_height:\n        raise ValueError(f\"Image height must be at most {max_height}px, got {height}px\")\n\n\ndef validate_image_aspect_ratio(\n    image: torch.Tensor,\n    min_ratio: tuple[float, float] | None = None,  # e.g. (1, 4)\n    max_ratio: tuple[float, float] | None = None,  # e.g. (4, 1)\n    *,\n    strict: bool = True,  # True -> (min, max); False -> [min, max]\n) -> float:\n    \"\"\"Validates that image aspect ratio is within min and max. If a bound is None, that side is not checked.\"\"\"\n    w, h = get_image_dimensions(image)\n    if w <= 0 or h <= 0:\n        raise ValueError(f\"Invalid image dimensions: {w}x{h}\")\n    ar = w / h","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/util/validation_utils.py#L11-L47","documentation":"ValueError from validate_image_dimensions when the image width exceeds the API/node maximum. Same dimension extraction as the other bounds checks: W is shape[2] for [B,H,W,C] tensors and shape[1] for [H,W,C]. It prevents sending images larger than the provider accepts.","triggerScenarios":"validate_image_dimensions(image, max_width=N) with width > N — e.g., a 4096px panorama passed to a node limiting max_width=3072.","commonSituations":"High-resolution outputs or upscaled images exceeding provider caps; panoramas and wide crops; forgetting to downscale before an API edit node.","solutions":["Downscale the image so width <= max_width (the message states both values).","If using upload_images_to_comfyapi, its total_pixels resampling may already shrink images — but explicit resize to within bounds is deterministic.","Tile or crop the image and process pieces separately if full resolution must be kept."],"exampleFix":"# before\nvalidate_image_dimensions(image, max_width=2048)  # image is 4096 wide\n# after\nscale = 2048 / image.shape[2]\nimage = torch.nn.functional.interpolate(image.permute(0,3,1,2), scale_factor=scale, mode='bilinear').permute(0,2,3,1)\nvalidate_image_dimensions(image, max_width=2048)","handlingStrategy":"validation","validationCode":"def clamp_width(image: torch.Tensor, max_width: int) -> torch.Tensor:\n    w = image.shape[2] if image.dim() == 4 else image.shape[1]\n    if w <= max_width:\n        return image\n    scale = max_width / w\n    perm = (0, 3, 1, 2) if image.dim() == 4 else (2, 0, 1)\n    return torch.nn.functional.interpolate(image.permute(*perm), scale_factor=scale, mode='bilinear').permute(*range(image.dim()))","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Downscale before API nodes when sources may exceed caps","Know each provider's max resolution and encode within it"],"tags":["validation","image","dimensions"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}