{"record":{"id":"3f6b0a0e1ec27088","repo":"sgl-project/sglang","slug":"reference-image-target-dimensions-must-be-aligned","errorCode":null,"errorMessage":"reference image target dimensions must be aligned to {MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE}","messagePattern":"reference image target dimensions must be aligned to (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/reference_encoding.py","lineNumber":197,"sourceCode":"\n\ndef minimax_h3_resize_reference_image(\n    image: Any,\n    *,\n    target_width: int,\n    target_height: int,\n) -> Any:\n    \"\"\"Resize a reference image to the shape fixed by pre-queue admission.\"\"\"\n\n    from PIL import Image\n\n    if target_width <= 0 or target_height <= 0:\n        raise ValueError(\"reference image target dimensions must be positive\")\n    if (\n        target_width % MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE\n        or target_height % MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE\n    ):\n        raise ValueError(\n            \"reference image target dimensions must be aligned to \"\n            f\"{MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE}\"\n        )\n    image = image.convert(\"RGB\")\n    if (target_width, target_height) == image.size:\n        return image\n    return image.resize((target_width, target_height), Image.Resampling.LANCZOS)\n\n\ndef _load_waveform(\n    path: str,\n    *,\n    material_chain: str = \"audio\",\n    max_duration_seconds: float | None = None,\n    start_time_seconds: float = 0.0,\n    source_sample_rate: int | None = None,\n) -> tuple[torch.Tensor, int]:\n    \"\"\"Apply the audio material chain.","sourceCodeStart":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/reference_encoding.py#L179-L215","documentation":"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.","triggerScenarios":"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.","commonSituations":"Code that rounds dimensions with int() or round() instead of _nearest_multiple, or a changed constant value after a version bump.","solutions":["Derive target dims from minimax_h3_resolve_reference_image_shape, which already aligns them","Round up to the next multiple: dim = ((dim + MULT - 1)//MULT)*MULT","Import the constant from the module rather than hardcoding a stale value"],"exampleFix":"// before\ntw, th = round(w*s), round(h*s)  # e.g. 513 -> unaligned\n\n// after\nM = MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE\ntw, th = _nearest_multiple(w*s, M), _nearest_multiple(h*s, M)","handlingStrategy":"validation","validationCode":"from ...minimax_h3.reference_encoding import MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE as M\n\ndef aligned(n) -> bool:\n    return n % M == 0","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use _nearest_multiple for any custom dimension math","Import the constant instead of hardcoding; it can change across versions"],"tags":["minimax-h3","alignment","resize"],"backgroundTag":"dimension-alignment-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}