{"record":{"id":"403cfb9dbb7c3fd9","repo":"Comfy-Org/ComfyUI","slug":"aspect-ratio-ar-2g-must-be-op-lo-2g","errorCode":null,"errorMessage":"Aspect ratio `{ar:.2g}` must be {op} {lo:.2g}.","messagePattern":"Aspect ratio `(.+?)` must be (.+?) (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/util/validation_utils.py","lineNumber":226,"sourceCode":"\ndef _assert_ratio_bounds(\n    ar: float,\n    *,\n    min_ratio: tuple[float, float] | None = None,\n    max_ratio: tuple[float, float] | None = None,\n    strict: bool = True,\n) -> None:\n    \"\"\"Validate a numeric aspect ratio against optional min/max ratio bounds.\"\"\"\n    lo = _ratio_from_tuple(min_ratio) if min_ratio is not None else None\n    hi = _ratio_from_tuple(max_ratio) if max_ratio is not None else None\n\n    if lo is not None and hi is not None and lo > hi:\n        lo, hi = hi, lo  # normalize order if caller swapped them\n\n    if lo is not None:\n        if (ar <= lo) if strict else (ar < lo):\n            op = \"<\" if strict else \"≤\"\n            raise ValueError(f\"Aspect ratio `{ar:.2g}` must be {op} {lo:.2g}.\")\n    if hi is not None:\n        if (ar >= hi) if strict else (ar > hi):\n            op = \"<\" if strict else \"≤\"\n            raise ValueError(f\"Aspect ratio `{ar:.2g}` must be {op} {hi:.2g}.\")\n\n\ndef _parse_aspect_ratio_string(ar_str: str) -> float:\n    \"\"\"Parse 'X:Y' with integer parts into a positive float ratio X/Y.\"\"\"\n    parts = ar_str.split(\":\")\n    if len(parts) != 2:\n        raise ValueError(f\"Aspect ratio must be 'X:Y' (e.g., 16:9), got '{ar_str}'.\")\n    try:\n        a = int(parts[0].strip())\n        b = int(parts[1].strip())\n    except ValueError as exc:\n        raise ValueError(f\"Aspect ratio must contain integers separated by ':', got '{ar_str}'.\") from exc\n    if a <= 0 or b <= 0:\n        raise ValueError(f\"Aspect ratio parts must be positive integers, got {a}:{b}.\")","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/util/validation_utils.py#L208-L244","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Move the aspect ratio inside the provider's documented range (commonly between 1:4 and 4:1).","If you intended the opposite orientation, check that width and height are not swapped in the upstream node.","Pick a preset ratio from the node's combo options instead of a custom extreme value.","If you need extreme aspect output, generate at the nearest allowed ratio and crop/outpaint locally."],"exampleFix":"# before\n_assert_ratio_bounds(0.2, min_ratio=(1, 4))  # ValueError: Aspect ratio `0.2` must be < 0.25.\n\n# after\n_assert_ratio_bounds(0.25, min_ratio=(1, 4), strict=False)  # boundary allowed\n# or use ar = 0.26 (e.g. 1:3.8) within bounds","handlingStrategy":"validation","validationCode":"MIN = 1/4  # provider bound\nif ar <= MIN:\n    ar = MIN + 1e-6  # or clamp to nearest allowed","typeGuard":null,"tryCatchPattern":"try: _assert_ratio_bounds(ar, min_ratio=(1,4)) except ValueError as e: raise UserVisibleError(str(e)) from e","preventionTips":["Stay inside provider ratio ranges (commonly 1:4 to 4:1).","Double-check width/height order before computing the ratio.","Prefer preset ratio options over custom extremes."],"tags":["api-nodes","validation","aspect-ratio"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}