sgl-project/sglang · error · ValueError

reference image target dimensions must be aligned to {MINIMA

Error message

reference image target dimensions must be aligned to {MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE}

What it means

MiniMax H3 resizes reference images to dimensions aligned to MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE (the VAE patch multiple). Passing unaligned target dimensions would break the encoder, so the resize helper rejects them.

Source

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

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",
    max_duration_seconds: float | None = None,
    start_time_seconds: float = 0.0,
    source_sample_rate: int | None = None,
) -> tuple[torch.Tensor, int]:
    """Apply the audio material chain.

View on GitHub (pinned to 0132848349)

Solutions

1. Derive target dims from minimax_h3_resolve_reference_image_shape, which already aligns them
2. Round up to the next multiple: dim = ((dim + MULT - 1)//MULT)*MULT
3. Import the constant from the module rather than hardcoding a stale value

Example fix

// before
tw, th = round(w*s), round(h*s)  # e.g. 513 -> unaligned

// after
M = MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE
tw, th = _nearest_multiple(w*s, M), _nearest_multiple(h*s, M)

from ...minimax_h3.reference_encoding import MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE as M

def aligned(n) -> bool:
    return n % M == 0

When it happens

Trigger: Calling minimax_h3_resize_reference_image with target dims not divisible by the multiple (e.g. 513x512 when the multiple is 32), typically from custom dimension math.

Common situations: Code that rounds dimensions with int() or round() instead of _nearest_multiple, or a changed constant value after a version bump.

Related errors

• seq_len {seq_len} < used rows {used}
• video block token counts and timestamps must align
• image_token_count required for an image reference
• video reference requires block token counts and timestamps
• unused image_token_count entries

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