{"record":{"id":"632666af0729ba98","repo":"Comfy-Org/ComfyUI","slug":"invalid-image-tensor-shape","errorCode":null,"errorMessage":"Invalid image tensor shape.","messagePattern":"Invalid image tensor shape\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/util/validation_utils.py","lineNumber":14,"sourceCode":"import logging\n\nimport torch\n\nfrom comfy_api.latest import Input\n\n\ndef get_image_dimensions(image: torch.Tensor) -> tuple[int, int]:\n    if len(image.shape) == 4:\n        return image.shape[1], image.shape[2]\n    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:","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/util/validation_utils.py#L1-L32","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the tensor is [H,W,C] or [B,H,W,C] float image format before calling validators.","If you have a 2-D grayscale array, add a channel dim: img = img[..., None] (then batch dim if needed).","If you have a CHW latent, decode it to image format with the VAE before validation; do not pass latents.","Print image.shape right before the call to confirm the rank."],"exampleFix":"# before\nvalidate_image_dimensions(mask_2d, min_width=64)\n# after\nimage = mask_2d.unsqueeze(-1)  # [H,W] -> [H,W,1]\nvalidate_image_dimensions(image, min_width=64)","handlingStrategy":"type-guard","validationCode":"def is_valid_image_rank(image: torch.Tensor) -> bool:\n    return isinstance(image, torch.Tensor) and image.dim() in (3, 4)","typeGuard":"def is_image_tensor(t: torch.Tensor) -> bool:\n    \"\"\"True for [H,W,C] or [B,H,W,C] float image tensors.\"\"\"\n    return isinstance(t, torch.Tensor) and t.dim() in (3, 4)","tryCatchPattern":"try:\n    validate_image_dimensions(image, min_width=64)\nexcept ValueError as e:\n    raise ValueError(f\"Bad input to node: {e}; got shape {tuple(image.shape)}\") from e","preventionTips":["Standardize on [B,H,W,C] image tensors in custom nodes","Never pass latents or 2-D masks where images are expected","Assert image.dim() early in node code"],"tags":["validation","tensor","image","shape"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}