sgl-project/sglang · error · ValueError

reference image ratio must be within the inclusive range 1:4

Error message

reference image ratio must be within the inclusive range 1:4 to 4:1, got {source_width:g}x{source_height:g}

What it means

MiniMax H3 enforces an aspect-ratio bound of 1:4 to 4:1 on reference images: the longer side may be at most four times the shorter side. This is a model-side constraint on the reference-image encoder and is checked during pre-queue shape resolution.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/reference_encoding.py:155

    try:
        source_width = float(width)
        source_height = float(height)
    except (TypeError, ValueError) as exc:
        raise ValueError(
            "reference image width and height must be positive finite numbers"
        ) from exc
    if (
        not math.isfinite(source_width)
        or not math.isfinite(source_height)
        or source_width <= 0.0
        or source_height <= 0.0
    ):
        raise ValueError(
            "reference image width and height must be positive finite numbers"
        )
    if source_width > 4.0 * source_height or source_height > 4.0 * source_width:
        raise ValueError(
            "reference image ratio must be within the inclusive range "
            f"1:4 to 4:1, got {source_width:g}x{source_height:g}"
        )

    scale = MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE / min(source_width, source_height)
    target_width = _nearest_multiple(
        source_width * scale, MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE
    )
    target_height = _nearest_multiple(
        source_height * scale, MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE
    )
    return {
        "geometry": "reference_image_resolved",
        "shape_policy_version": "reference_image_short_edge_v1",
        "base_short_edge": MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE,
        "effective_short_edge": min(target_width, target_height),
        "size_mode": "short_edge",
        "multiple": MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE,

View on GitHub (pinned to 0132848349)

Solutions

1. Crop or letterbox the image to within 1:4..4:1 before submitting (e.g. pad the short side)
2. Reject the request client-side with a clear aspect-ratio message
3. Center-crop to a bounded ratio such as 1:1 or 16:9 if padding is unacceptable

Example fix

// before
img = PIL.Image.open(path)  # 2000x200 -> ValueError downstream

// after
w, h = img.size
if w > 4*h: img = img.crop((0,0,4*h,h))
elif h > 4*w: img = img.crop((0,0,w,4*w))

def ratio_ok(w, h, limit=4.0) -> bool:
    return w <= limit * h and h <= limit * w

try:
    minimax_h3_prepare_for_queue(batch)
except ValueError as e:
    if 'ratio' in str(e):
        crop_to_ratio(image); retry=True
    else:
        raise

When it happens

Trigger: Passing a reference image with an extreme aspect ratio, e.g. 1000x100 (10:1) or 200x2000, into minimax_h3_prepare_for_queue / the image reference chain.

Common situations: Users uploading panoramic strips, tall screenshots, banners, or any skinny elongated image as a style/identity reference.

Related errors

• {path}.aspect_ratio must be "auto" for task {profile.task!r}
• {path}.aspect_ratio for task {profile.task!r} must be 'auto'
• target.aspect_ratio must be 'W:H' or 'auto', got {value!r}
• target.aspect_ratio must be integer 'W:H', got {value!r}
• target.aspect_ratio components must be positive, got {value!

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/95acb201a7cd3aeb. Report an issue: GitHub.