sgl-project/sglang · error · ValueError

image_mode='{mode}' is not supported with multiple images (g

Error message

image_mode='{mode}' is not supported with multiple images (got {num_images} images). Please use one of: {allowed}

What it means

Only the lightweight OCR modes ('tiny', 'small', 'base') support multi-image requests. When num_images > 1 and the resolved mode key is not in _MULTI_IMAGE_ALLOWED, the processor raises ValueError telling you to switch modes. This prevents resolution-heavy modes from multiplying crop windows across many images.

Source

Thrown at python/sglang/srt/multimodal/processors/unlimited_ocr.py:46

def _resolve_mode(images_config, num_images: int = 1) -> dict:
    """Return processor kwargs from images_config (or default)."""
    mode = _DEFAULT_MODE
    if images_config:
        mode = images_config.get("image_mode", _DEFAULT_MODE)
    key = mode.strip().lower()
    preset = _IMAGE_MODE_PRESETS.get(key)
    if preset is None:
        logger.error(
            f"Unknown image_mode '{mode}'. Supported: {', '.join(_IMAGE_MODE_PRESETS)}"
        )
        raise ValueError(
            f"Unknown image_mode '{mode}'. "
            f"Supported: {', '.join(_IMAGE_MODE_PRESETS)}"
        )
    _MULTI_IMAGE_ALLOWED = ("tiny", "small", "base")
    base_size, image_size, crop_mode = preset
    if num_images > 1 and key not in _MULTI_IMAGE_ALLOWED:
        raise ValueError(
            f"image_mode='{mode}' is not supported with multiple images "
            f"(got {num_images} images). "
            f"Please use one of: {list(_MULTI_IMAGE_ALLOWED)}"
        )
    return dict(zip(("base_size", "image_size", "crop_mode"), preset))


class UnlimitedOCRProcessor(BaseMultimodalProcessor):
    """Multimodal processor for UNLIMITED-OCR model."""

    models = [UnlimitedOCRForCausalLM]
    gpu_image_decode = False

    def __init__(self, hf_config, server_args, _processor, *args, **kwargs):
        """Initialize UnlimitedOCRProcessor."""
        super().__init__(hf_config, server_args, _processor, *args, **kwargs)
        self.mm_tokens = MultimodalSpecialTokens(
            image_token="<image>", image_token_id=self._processor.image_token_id

View on GitHub (pinned to 0132848349)

Solutions

1. Switch image_mode to 'tiny', 'small', or 'base' for multi-image requests
2. Split the request into one image per request to keep the heavy mode
3. Pre-validate mode vs image count client-side before sending

Example fix

# before
image_mode='hd'; images=[page1, page2]
# after
image_mode='base'; images=[page1, page2]

MULTI_OK = ('tiny', 'small', 'base')
if len(images) > 1 and image_mode.strip().lower() not in MULTI_OK:
    image_mode = 'base'  # or reject

When it happens

Trigger: Sending a request with 2+ images while image_mode resolves to a multi-image-disallowed preset (any preset outside tiny/small/base).

Common situations: Batching document pages with a high-resolution mode; per-image mode overrides not applied so a global heavy mode is used for a multi-page scan request.

Related errors

• Unknown image_mode '{mode}'. Supported: {supported}
• Attention backend '{selected_backend}' is not supported by t
• Unknown image_vae_encoding_position: {image_vae_encoding_pos
• memory_position_mode must be one of {'reference', 'legacy',
• projection_cls = {projection_cls}, not implemented

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