Comfy-Org/ComfyUI · error · ValueError

Image width must be at least {min_width}px, got {width}px

Error message

Image width must be at least {min_width}px, got {width}px

What it means

ValueError from validate_image_dimensions when the computed image width is below the node/API's minimum width. Height/width come from get_image_dimensions ([B,H,W,C] uses shape[1]=H, shape[2]=W; [H,W,C] uses shape[0]=H, shape[1]=W). This guard rejects images too small for the target API before any network call.

Source

Thrown at comfy_api_nodes/util/validation_utils.py:27

    if len(image.shape) == 4:
        return image.shape[1], image.shape[2]
    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:

View on GitHub (pinned to 1c6d8d45b3)

Solutions

  1. Upscale or re-generate the image so width >= min_width shown in the message.
  2. Fix upstream resize/crop nodes that shrank the image.
  3. Choose a different API node/model with lower minimum resolution requirements.

Example fix

# before
validate_image_dimensions(image, min_width=1024)  # image is 512 wide
# after
image = torch.nn.functional.interpolate(image.permute(0,3,1,2), scale_factor=2, mode='bilinear').permute(0,2,3,1)
validate_image_dimensions(image, min_width=1024)
Defensive patterns

Strategy: validation

Validate before calling

def check_min_width(image: torch.Tensor, min_width: int) -> bool:
    w = image.shape[2] if image.dim() == 4 else image.shape[1]
    return w >= min_width

Try / catch

if not check_min_width(image, MIN_W):
    raise ValueError(f"image too small: need width >= {MIN_W}")
validate_image_dimensions(image, min_width=MIN_W)

Prevention

When it happens

Trigger: Calling validate_image_dimensions(image, min_width=N) with width < N — e.g., a 512px-wide image passed to an API node whose model requires min_width=768 (typical for OpenAI/generation endpoints with minimum resolution requirements).

Common situations: Downscaled or heavily resized images falling under provider minimums; small crops; chaining a resize node with too-small dimensions before an API image node.

Related errors

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