Comfy-Org/ComfyUI · error · ValueError

Aspect ratio must be 'X:Y' (e.g., 16:9), got '{ar_str}'.

Error message

Aspect ratio must be 'X:Y' (e.g., 16:9), got '{ar_str}'.

What it means

Raised by _parse_aspect_ratio_string() in comfy_api_nodes/util/validation_utils.py when a string aspect ratio does not contain exactly one ':' separator. The helper is used by the public validate_aspect_ratio() to accept widget values like '16:9'; it splits on ':' and requires exactly two parts before attempting integer parsing.

Source

Thrown at comfy_api_nodes/util/validation_utils.py:237

    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}.")
    return a / b

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Format the ratio as 'X:Y' with integer parts, e.g. '16:9' or '4:3'.
2. Convert decimals to the nearest integer ratio before passing (1.78 -> '16:9').
3. Prefer the node's preset ratio dropdown over free-text entry.
4. If calling from code, emit f'{w}:{h}' from integer width/height.

Example fix

# before
_parse_aspect_ratio_string('16x9')  # ValueError: Aspect ratio must be 'X:Y' (e.g., 16:9), got '16x9'.

# after
_parse_aspect_ratio_string('16:9')  # -> 1.777...

def is_ratio_string(s) -> bool:
    return isinstance(s, str) and len(s.split(':')) == 2

if not is_ratio_string(ratio_str):
    raise ValueError(f"ratio must be 'X:Y', got {ratio_str!r}")

def is_ratio_string(s) -> bool:
    return isinstance(s, str) and len(s.split(':')) == 2

When it happens

Trigger: Passing '16x9', '1.77', '16-9', '169', or '16:9:2' as an aspect-ratio string to a node that validates via validate_aspect_ratio('16x9'). Only the exact 'X:Y' two-part form is accepted.

Common situations: Custom-ratio widgets where users type the decimal form (1.78) common in other tools; pasted ratios with en-dashes or 'x' separators; API callers constructing the field programmatically with a float instead of the string form.

Related errors

• Aspect ratio must contain integers separated by ':', got '{a
• Aspect ratio parts must be positive integers, got {a}:{b}.
• Ratios must be positive, got {a}:{b}.
• Aspect ratio `{ar:.2g}` must be {op} {lo:.2g}.
• Aspect ratio `{ar:.2g}` must be {op} {hi:.2g}.

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