Comfy-Org/ComfyUI · error · ValueError

Image height must be at most {max_height}px, got {height}px

Error message

Image height must be at most {max_height}px, got {height}px

What it means

ValueError from validate_image_dimensions when image height exceeds the allowed maximum. Mirrors the max_width check: height comes from get_image_dimensions and is compared to max_height when provided. Fails before upload so oversized images never reach the API.

Source

Thrown at comfy_api_nodes/util/validation_utils.py:33

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
    _assert_ratio_bounds(ar, min_ratio=min_ratio, max_ratio=max_ratio, strict=strict)
    return ar

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Downscale so height <= max_height.
2. Crop or split tall images and process in chunks.
3. Adjust the workflow's upscale factor to stay under the cap.

def check_max_height(image: torch.Tensor, max_height: int) -> bool:
    h = image.shape[1] if image.dim() == 4 else image.shape[0]
    return h <= max_height

When it happens

Trigger: validate_image_dimensions(image, max_height=N) with height > N — e.g., a 4096px-tall image into a node capping max_height=2048.

Common situations: Upscaled or stitched tall images; print/poster-resolution outputs; forgetting downscale before an API node.

Related errors

• Image width must be at least {min_width}px, got {width}px
• Image width must be at most {max_width}px, got {width}px
• Image height must be at least {min_height}px, got {height}px
• The maximum number of reference images is 10.
• sync.so rejects images above 4K (4096x2160); got {width}x{he

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