sgl-project/sglang · error · ValueError

reference image target dimensions must be positive

Error message

reference image target dimensions must be positive

What it means

The resize helper for MiniMax H3 reference images requires strictly positive integer target dimensions. It is normally fed dimensions produced by minimax_h3_resolve_reference_image_shape, so hitting this means the caller bypassed or corrupted the admission path.

Source

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

        "rounding": "nearest",
        "allow_upscale": True,
        "width": target_width,
        "height": target_height,
    }


def minimax_h3_resize_reference_image(
    image: Any,
    *,
    target_width: int,
    target_height: int,
) -> Any:
    """Resize a reference image to the shape fixed by pre-queue admission."""

    from PIL import Image

    if target_width <= 0 or target_height <= 0:
        raise ValueError("reference image target dimensions must be positive")
    if (
        target_width % MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE
        or target_height % MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE
    ):
        raise ValueError(
            "reference image target dimensions must be aligned to "
            f"{MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE}"
        )
    image = image.convert("RGB")
    if (target_width, target_height) == image.size:
        return image
    return image.resize((target_width, target_height), Image.Resampling.LANCZOS)


def _load_waveform(
    path: str,
    *,
    material_chain: str = "audio",

View on GitHub (pinned to 0132848349)

Solutions

1. Use the (width,height) returned by minimax_h3_resolve_reference_image_shape rather than computing your own
2. Check for <=0 before calling and fall back to the resolver
3. If intercepting the pipeline, don't rewrite the prepared-image extra cache with zeroed dims

Example fix

// before
img = minimax_h3_resize_reference_image(img, 0, 512)

// after
tw, th = minimax_h3_resolve_reference_image_shape(img.size[0], img.size[1])
img = minimax_h3_resize_reference_image(img, tw, th)

def valid_target(w, h) -> bool:
    return isinstance(w, int) and isinstance(h, int) and w > 0 and h > 0

When it happens

Trigger: Calling minimax_h3_resize_reference_image / minimax_h3_prepared_reference_image directly with target_width or target_height <= 0, or hand-computing target dims that underflow to 0.

Common situations: Custom preprocessing code computing target dimensions with a bad scale factor (e.g. scale rounding to 0) instead of using the resolver's output.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• MiniMax H3 AdaLN cache takes exactly one of path (prebuilt s
• MiniMax H3 AdaLN cache max_plans must be positive
• MiniMax H3 AdaLN cache max_plan_width must be positive; set
• reference image target dimensions must be aligned to {MINIMA
• attn_sink requires topk_length to be provided as well

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