Comfy-Org/ComfyUI · error · ValueError

Aspect ratio `{ar:.2g}` must be {op} {lo:.2g}.

Error message

Aspect ratio `{ar:.2g}` must be {op} {lo:.2g}.

What it means

Raised by _assert_ratio_bounds() in comfy_api_nodes/util/validation_utils.py when a numeric aspect ratio is at or below the provider's minimum ratio (strict mode, default) or strictly below it (non-strict). The op embedded in the message is '<' — i.e. the message reads 'ratio must be < min', phrased from the failing comparison; bounds are normalized so swapped min/max tuples are tolerated.

Source

Thrown at comfy_api_nodes/util/validation_utils.py:226

def _assert_ratio_bounds(
    ar: float,
    *,
    min_ratio: tuple[float, float] | None = None,
    max_ratio: tuple[float, float] | None = None,
    strict: bool = True,
) -> None:
    """Validate a numeric aspect ratio against optional min/max ratio bounds."""
    lo = _ratio_from_tuple(min_ratio) if min_ratio is not None else None
    hi = _ratio_from_tuple(max_ratio) if max_ratio is not None else None

    if lo is not None and hi is not None and lo > hi:
        lo, hi = hi, lo  # normalize order if caller swapped them

    if lo is not None:
        if (ar <= lo) if strict else (ar < lo):
            op = "<" if strict else "≤"
            raise ValueError(f"Aspect ratio `{ar:.2g}` must be {op} {lo:.2g}.")
    if hi is not None:
        if (ar >= hi) if strict else (ar > hi):
            op = "<" if strict else "≤"
            raise ValueError(f"Aspect ratio `{ar:.2g}` must be {op} {hi:.2g}.")


def _parse_aspect_ratio_string(ar_str: str) -> float:
    """Parse 'X:Y' with integer parts into a positive float ratio X/Y."""
    parts = ar_str.split(":")
    if len(parts) != 2:
        raise ValueError(f"Aspect ratio must be 'X:Y' (e.g., 16:9), got '{ar_str}'.")
    try:
        a = int(parts[0].strip())
        b = int(parts[1].strip())
    except ValueError as exc:
        raise ValueError(f"Aspect ratio must contain integers separated by ':', got '{ar_str}'.") from exc
    if a <= 0 or b <= 0:
        raise ValueError(f"Aspect ratio parts must be positive integers, got {a}:{b}.")

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Move the aspect ratio inside the provider's documented range (commonly between 1:4 and 4:1).
2. If you intended the opposite orientation, check that width and height are not swapped in the upstream node.
3. Pick a preset ratio from the node's combo options instead of a custom extreme value.
4. If you need extreme aspect output, generate at the nearest allowed ratio and crop/outpaint locally.

Example fix

# before
_assert_ratio_bounds(0.2, min_ratio=(1, 4))  # ValueError: Aspect ratio `0.2` must be < 0.25.

# after
_assert_ratio_bounds(0.25, min_ratio=(1, 4), strict=False)  # boundary allowed
# or use ar = 0.26 (e.g. 1:3.8) within bounds

MIN = 1/4  # provider bound
if ar <= MIN:
    ar = MIN + 1e-6  # or clamp to nearest allowed

try: _assert_ratio_bounds(ar, min_ratio=(1,4)) except ValueError as e: raise UserVisibleError(str(e)) from e

When it happens

Trigger: Calling a node wrapped with _assert_ratio_bounds(ar, min_ratio=(1,4)) with ar <= 0.25 (e.g. a 1:5 tall image). Strict mode (default) also rejects the exact boundary value ar == lo; non-strict (strict=False) allows equality.

Common situations: Users enter extreme aspect ratios like 1:10 for banner/poster generation that the provider (image-gen APIs commonly clamp to 1:4..4:1) does not support; or width/height inputs are swapped so the ratio inverts past the bound.

Related errors

• Ratios must be positive, got {a}:{b}.
• Aspect ratio `{ar:.2g}` must be {op} {hi:.2g}.
• Aspect ratio must be 'X:Y' (e.g., 16:9), got '{ar_str}'.
• Aspect ratio must contain integers separated by ':', got '{a
• Aspect ratio parts must be positive integers, got {a}:{b}.

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