Comfy-Org/ComfyUI · error · ValueError

Image width must be at most {max_width}px, got {width}px

Error message

Image width must be at most {max_width}px, got {width}px

What it means

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.

Source

Thrown at comfy_api_nodes/util/validation_utils.py:29

    elif len(image.shape) == 3:
        return image.shape[0], image.shape[1]
    else:
        raise ValueError("Invalid image tensor shape.")


def validate_image_dimensions(
    image: torch.Tensor,
    min_width: int | None = None,
    max_width: int | None = None,
    min_height: int | None = None,
    max_height: int | None = None,
):
    height, width = get_image_dimensions(image)

    if min_width is not None and width < min_width:
        raise ValueError(f"Image width must be at least {min_width}px, got {width}px")
    if max_width is not None and width > max_width:
        raise ValueError(f"Image width must be at most {max_width}px, got {width}px")
    if min_height is not None and height < min_height:
        raise ValueError(f"Image height must be at least {min_height}px, got {height}px")
    if max_height is not None and height > max_height:
        raise ValueError(f"Image height must be at most {max_height}px, got {height}px")


def validate_image_aspect_ratio(
    image: torch.Tensor,
    min_ratio: tuple[float, float] | None = None,  # e.g. (1, 4)
    max_ratio: tuple[float, float] | None = None,  # e.g. (4, 1)
    *,
    strict: bool = True,  # True -> (min, max); False -> [min, max]
) -> float:
    """Validates that image aspect ratio is within min and max. If a bound is None, that side is not checked."""
    w, h = get_image_dimensions(image)
    if w <= 0 or h <= 0:
        raise ValueError(f"Invalid image dimensions: {w}x{h}")
    ar = w / h

View on GitHub (pinned to 1c6d8d45b3)

Solutions

  1. Downscale the image so width <= max_width (the message states both values).
  2. If using upload_images_to_comfyapi, its total_pixels resampling may already shrink images — but explicit resize to within bounds is deterministic.
  3. Tile or crop the image and process pieces separately if full resolution must be kept.

Example fix

# before
validate_image_dimensions(image, max_width=2048)  # image is 4096 wide
# after
scale = 2048 / image.shape[2]
image = torch.nn.functional.interpolate(image.permute(0,3,1,2), scale_factor=scale, mode='bilinear').permute(0,2,3,1)
validate_image_dimensions(image, max_width=2048)
Defensive patterns

Strategy: validation

Validate before calling

def clamp_width(image: torch.Tensor, max_width: int) -> torch.Tensor:
    w = image.shape[2] if image.dim() == 4 else image.shape[1]
    if w <= max_width:
        return image
    scale = max_width / w
    perm = (0, 3, 1, 2) if image.dim() == 4 else (2, 0, 1)
    return torch.nn.functional.interpolate(image.permute(*perm), scale_factor=scale, mode='bilinear').permute(*range(image.dim()))

Prevention

When it happens

Trigger: validate_image_dimensions(image, max_width=N) with width > N — e.g., a 4096px panorama passed to a node limiting max_width=3072.

Common situations: High-resolution outputs or upscaled images exceeding provider caps; panoramas and wide crops; forgetting to downscale before an API edit node.

Related errors

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