{"record":{"id":"644e5263592abe7d","repo":"Comfy-Org/ComfyUI","slug":"aspect-ratios-must-be-close-ar1-ar2-ar1-ar2-2g","errorCode":null,"errorMessage":"Aspect ratios must be close: ar1/ar2={ar1/ar2:.2g}, allowed range {min_rel}–{max_rel} (limit {limit:.2g}).","messagePattern":"Aspect ratios must be close: ar1/ar2=(.+?), allowed range (.+?)–(.+?) \\(limit (.+?)\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/util/validation_utils.py","lineNumber":76,"sourceCode":"    strict: bool = False,  # True -> (min, max); False -> [min, max]\n) -> float:\n    \"\"\"\n    Validates that the two images' aspect ratios are 'close'.\n    The closeness factor is C = max(ar1, ar2) / min(ar1, ar2)  (C >= 1).\n    We require C <= limit, where limit = max(max_rel, 1.0 / min_rel).\n\n    Returns the computed closeness factor C.\n    \"\"\"\n    w1, h1 = get_image_dimensions(first_image)\n    w2, h2 = get_image_dimensions(second_image)\n    if min(w1, h1, w2, h2) <= 0:\n        raise ValueError(\"Invalid image dimensions\")\n    ar1 = w1 / h1\n    ar2 = w2 / h2\n    closeness = max(ar1, ar2) / min(ar1, ar2)\n    limit = max(max_rel, 1.0 / min_rel)\n    if (closeness >= limit) if strict else (closeness > limit):\n        raise ValueError(\n            f\"Aspect ratios must be close: ar1/ar2={ar1/ar2:.2g}, \"\n            f\"allowed range {min_rel}–{max_rel} (limit {limit:.2g}).\"\n        )\n    return closeness\n\n\ndef validate_aspect_ratio_string(\n    aspect_ratio: str,\n    min_ratio: tuple[float, float] | None = None,  # e.g. (1, 4)\n    max_ratio: tuple[float, float] | None = None,  # e.g. (4, 1)\n    *,\n    strict: bool = False,  # True -> (min, max); False -> [min, max]\n) -> float:\n    \"\"\"Parses 'X:Y' and validates it against optional bounds. Returns the numeric ratio.\"\"\"\n    ar = _parse_aspect_ratio_string(aspect_ratio)\n    _assert_ratio_bounds(ar, min_ratio=min_ratio, max_ratio=max_ratio, strict=strict)\n    return ar\n","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/util/validation_utils.py#L58-L94","documentation":"ValueError from validate_images_aspect_ratio_closeness when the two images' aspect ratios differ too much: closeness C = max(ar1,ar2)/min(ar1,ar2) must stay under limit = max(max_rel, 1/min_rel). With strict=True the comparison is >= (limit itself fails); with strict=False only values strictly above limit fail. Used by nodes that need paired images (e.g., image+mask or first/last frame) to match proportions.","triggerScenarios":"Passing e.g. a 16:9 image and a 1:1 image with limit ~1.25: C = 1.78 > 1.25, so the ValueError with ar1/ar2 and the allowed range is raised at validation_utils.py:76.","commonSituations":"Mixing portrait and landscape sources; a mask or reference frame generated at a different resolution than the main image; resizing one input but not the other in the workflow.","solutions":["Crop (not stretch) one image to the other's aspect ratio before pairing.","Generate the reference/mask at the same resolution and aspect as the main image.","If slight mismatch is acceptable, widen min_rel/max_rel only if the target API tolerates it — the limit exists because providers distort or reject mismatched pairs."],"exampleFix":"# before\nvalidate_images_aspect_ratio_closeness(img_16x9, img_1x1, min_rel=0.8, max_rel=1.25)\n# after\n# center-crop the 16:9 image to 1:1 first\ncrop = min(h, w)\nimg_sq = img_16x9[:, :crop, (w - crop) // 2:(w + crop) // 2, :]\nvalidate_images_aspect_ratio_closeness(img_sq, img_1x1, min_rel=0.8, max_rel=1.25)","handlingStrategy":"validation","validationCode":"def aspect_ratio(image: torch.Tensor) -> float:\n    h = image.shape[1] if image.dim() == 4 else image.shape[0]\n    w = image.shape[2] if image.dim() == 4 else image.shape[1]\n    return w / h\n\ndef ratios_close(a: torch.Tensor, b: torch.Tensor, limit: float = 1.25) -> bool:\n    ar1, ar2 = aspect_ratio(a), aspect_ratio(b)\n    return max(ar1, ar2) / min(ar1, ar2) < limit","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Generate reference/mask inputs at the same resolution as the main image","Center-crop (never stretch) to align aspect ratios before pairing"],"tags":["validation","image","aspect-ratio"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}