{"record":{"id":"882aecf54463e7e1","repo":"unslothai/unsloth","slug":"the-source-image-has-no-usable-aspect-ratio-aspe","errorCode":null,"errorMessage":"The source image has no usable aspect ratio ({aspect_width}x{aspect_height}).","messagePattern":"The source image has no usable aspect ratio \\((.+?)x(.+?)\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":400,"severity":"error","filePath":"studio/backend/core/inference/video_minimax_h3.py","lineNumber":259,"sourceCode":"H3_CANVAS_SHORT_EDGE = 768\nH3_CANVAS_MAX_PIXELS = 768 * 1344\nH3_CANVAS_MULTIPLE = 32\n# Trained aspect-ratio range.\nH3_MIN_ASPECT_RATIO = 1 / 4\nH3_MAX_ASPECT_RATIO = 4\n\n# Upstream stretches the first frame and center cover-crops the last.\nH3_ANCHOR_FIRST = \"first\"\nH3_ANCHOR_LAST = \"last\"\n\n\ndef h3_canvas_for_aspect(aspect_width: float, aspect_height: float) -> tuple[int, int]:\n    \"\"\"Resolve MiniMax-H3's canvas for an aspect ratio.\n\n    Raises ValueError outside the trained 1:4 to 4:1 range.\n    \"\"\"\n    if aspect_width <= 0 or aspect_height <= 0:\n        raise ValueError(\n            f\"The source image has no usable aspect ratio ({aspect_width}x{aspect_height}).\"\n        )\n    ratio = aspect_width / aspect_height\n    if not H3_MIN_ASPECT_RATIO <= ratio <= H3_MAX_ASPECT_RATIO:\n        raise ValueError(\n            f\"MiniMax-H3 supports aspect ratios from 1:4 to 4:1; this image is \"\n            f\"{aspect_width:g}x{aspect_height:g} ({ratio:.2f}:1). Crop it first.\"\n        )\n    if ratio >= 1.0:\n        width, height = H3_CANVAS_SHORT_EDGE * ratio, float(H3_CANVAS_SHORT_EDGE)\n    else:\n        width, height = float(H3_CANVAS_SHORT_EDGE), H3_CANVAS_SHORT_EDGE / ratio\n    area = width * height\n    if area > H3_CANVAS_MAX_PIXELS:\n        scale = math.sqrt(H3_CANVAS_MAX_PIXELS / area)\n        width, height = width * scale, height * scale\n    snap = lambda v: max(  # noqa: E731\n        H3_CANVAS_MULTIPLE, round(v / H3_CANVAS_MULTIPLE) * H3_CANVAS_MULTIPLE","sourceCodeStart":241,"sourceCodeEnd":277,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/video_minimax_h3.py#L241-L277","documentation":"h3_canvas_for_aspect raises ValueError when aspect_width or aspect_height is <= 0, i.e. the source image has a degenerate dimension so the aspect ratio is undefined (division would produce zero/infinity/NaN). This is the guard before the ratio math and the 1:4..4:1 range check, so a 0x0 or negative-dimension image fails here rather than producing nonsense canvas sizes.","triggerScenarios":"Calling h3_canvas_for_aspect(0, 0), (0, 512), or with negative dims; passing a placeholder/uninitialized image whose size tuple is (0, 0); a fully transparent or failed decode upstream reporting zero size.","commonSituations":"Bugs where an image object was created but never loaded (PIL Image.new with 0 size, or a failed download handing back a stub); metadata-driven code computing size from arithmetic that can go to zero.","solutions":["Validate the source image has width > 0 and height > 0 before calling (or before upload).","Fix the upstream image load that produced a zero/negative dimension.","Reject empty uploads at the request boundary with a clear 400."],"exampleFix":"# before\ncanvas = h3_canvas_for_aspect(img.width, img.height)  # img is 0x0 -> ValueError\n\n# after\nif img.width <= 0 or img.height <= 0:\n    raise HTTPException(400, \"source image is empty\")\ncanvas = h3_canvas_for_aspect(img.width, img.height)","handlingStrategy":"validation","validationCode":"if img.width <= 0 or img.height <= 0:\n    raise ValueError(f\"source image is empty ({img.width}x{img.height})\")\ncanvas = h3_canvas_for_aspect(img.width, img.height)","typeGuard":"def has_usable_size(img) -> bool:\n    return img.width > 0 and img.height > 0","tryCatchPattern":"try:\n    canvas = h3_canvas_for_aspect(w, h)\nexcept ValueError as e:\n    if \"no usable aspect ratio\" in str(e):\n        raise HTTPException(400, \"source image is empty or corrupt\") from e\n    raise","preventionTips":["Check width/height > 0 immediately after loading any user image.","Treat 0x0 images as load failures upstream (failed download/decode).","Validate at the request boundary, not deep in the generation pipeline."],"tags":["video","minimax-h3","image","validation"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}