Comfy-Org/ComfyUI · error · ValueError

Image aspect ratio is too extreme ({width}x{height}); FLUX 3

Error message

Image aspect ratio is too extreme ({width}x{height}); FLUX 3 accepts at most {_FLUX3_MAX_IMAGE_ASPECT}:1.

What it means

FLUX 3 video rejects reference images whose aspect ratio exceeds 64:1 (after also requiring each side >= 256px). The helper reads height/width from the tensor's last two dims and raises before any API call when max(side)/min(side) > _FLUX3_MAX_IMAGE_ASPECT.

Source

Thrown at comfy_api_nodes/nodes_bfl.py:1033

        )
        return IO.NodeOutput(await download_url_to_image_tensor(response.result["sample"]))


_FLUX3_ASPECT_RATIOS = ["auto", "21:9", "2:1", "16:9", "4:3", "1:1", "3:4", "9:16"]
_FLUX3_MIN_DURATION = 5
_FLUX3_MAX_DURATION = 20
_FLUX3_DURATIONS = ["auto"] + [str(i) for i in range(_FLUX3_MIN_DURATION, _FLUX3_MAX_DURATION + 1)]
_FLUX3_RESOLUTIONS = {"720p": "hd", "1080p": "fhd"}
_FLUX3_MAX_IMAGES = 10
_FLUX3_MIN_IMAGE_SIDE = 256
_FLUX3_MAX_IMAGE_ASPECT = 64


def _flux3_validate_image(image: torch.Tensor) -> None:
    validate_image_dimensions(image, min_width=_FLUX3_MIN_IMAGE_SIDE, min_height=_FLUX3_MIN_IMAGE_SIDE)
    height, width = image.shape[-3], image.shape[-2]
    if max(width, height) > _FLUX3_MAX_IMAGE_ASPECT * min(width, height):
        raise ValueError(
            f"Image aspect ratio is too extreme ({width}x{height}); "
            f"FLUX 3 accepts at most {_FLUX3_MAX_IMAGE_ASPECT}:1."
        )


def _flux3_collect_images(images: dict | None, field_name: str) -> list[torch.Tensor]:
    """Flatten Autogrow slots (each possibly batched) into single images and validate them."""
    flat: list[torch.Tensor] = []
    for tensor in (images or {}).values():
        if tensor is None:
            continue
        if tensor.ndim == 4:
            flat.extend(tensor[i] for i in range(tensor.shape[0]))
        else:
            flat.append(tensor)
    if len(flat) > _FLUX3_MAX_IMAGES:
        raise ValueError(f"FLUX 3 supports at most {_FLUX3_MAX_IMAGES} {field_name}, got {len(flat)}.")
    for tensor in flat:

View on GitHub (pinned to 1c6d8d45b3)

Solutions

Crop or resize the image so the longer side is at most 64x the shorter side (e.g. center-crop to a sane ratio).
If the image is actually multiple frames, split it into individual frames instead of passing a strip.
Check for accidental dimension swaps (HxW vs WxH) in upstream processing.

Example fix

# before
img = panorama  # 8192 x 96 -> ValueError

# after
from PIL import Image
img = center_crop(img, target_ratio=16/9)

Defensive patterns

Strategy: validation

Validate before calling

h, w = image.shape[-3], image.shape[-2]
assert max(h, w) <= 64 * min(h, w), f"aspect too extreme {w}x{h}"

Type guard

def flux3_aspect_ok(image: torch.Tensor) -> bool:
    h, w = image.shape[-3], image.shape[-2]
    return max(h, w) <= 64 * min(h, w) and min(h, w) >= 256

Prevention

Split film strips into individual frames instead of one huge image.
Validate dimensions before wiring images into FLUX 3 nodes.
Watch for accidental H/W swaps in resize logic.

When it happens

Trigger: Passing an extremely wide or tall keyframe/first-frame image (e.g. 8192x64 panorama or a slit strip) into a FLUX 3 video node.

Common situations: Feeding film-strip or sprite-sheet concatenations as a single image; letterboxed content with huge transparent borders; upstream resize nodes configured with extreme stretching.

Related errors

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