Comfy-Org/ComfyUI · error · ValueError

Invalid image tensor shape.

Error message

Invalid image tensor shape.

What it means

ValueError from get_image_dimensions when the image tensor is neither rank 4 ([B,H,W,C] -> returns shape[1],shape[2]) nor rank 3 ([H,W,C] -> returns shape[0],shape[1]). ComfyUI image tensors are CHW-unpacked HW[B]C-style batches; any other rank (e.g., a 2-D grayscale matrix, a 5-D tensor, or a non-tensor) is rejected before dimension/aspect validation.

Source

Thrown at comfy_api_nodes/util/validation_utils.py:14

import logging

import torch

from comfy_api.latest import Input


def get_image_dimensions(image: torch.Tensor) -> tuple[int, int]:
    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:

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Ensure the tensor is [H,W,C] or [B,H,W,C] float image format before calling validators.
2. If you have a 2-D grayscale array, add a channel dim: img = img[..., None] (then batch dim if needed).
3. If you have a CHW latent, decode it to image format with the VAE before validation; do not pass latents.
4. Print image.shape right before the call to confirm the rank.

Example fix

# before
validate_image_dimensions(mask_2d, min_width=64)
# after
image = mask_2d.unsqueeze(-1)  # [H,W] -> [H,W,1]
validate_image_dimensions(image, min_width=64)

def is_valid_image_rank(image: torch.Tensor) -> bool:
    return isinstance(image, torch.Tensor) and image.dim() in (3, 4)

def is_image_tensor(t: torch.Tensor) -> bool:
    """True for [H,W,C] or [B,H,W,C] float image tensors."""
    return isinstance(t, torch.Tensor) and t.dim() in (3, 4)

try:
    validate_image_dimensions(image, min_width=64)
except ValueError as e:
    raise ValueError(f"Bad input to node: {e}; got shape {tuple(image.shape)}") from e

When it happens

Trigger: Passing a tensor with len(shape) not in {3,4} to validate_image_dimensions or validate_image_aspect_ratio (both call get_image_dimensions); e.g., a 2-D [H,W] mask, a 5-D nested batch, or an image that was squeezed/unsqueezed incorrectly upstream.

Common situations: Feeding a mask or grayscale array directly where an image tensor is expected; a node upstream returning an unexpected rank; manually reshaping latent-space tensors (4-D [B,C,H,W]) which are channel-first, not image format.

Related errors

• Invalid image dimensions: {w}x{h}
• Invalid image dimensions
• JoyImage reference inputs must contain one image each
• 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/632666af0729ba98. Report an issue: GitHub.