sgl-project/sglang · error · ValueError

Unknown image_mode '{mode}'. Supported: {supported}

Error message

Unknown image_mode '{mode}'. Supported: {supported}

What it means

The unlimited OCR multimodal processor maps a named image_mode (e.g. 'tiny', 'small', 'base') to a (base_size, image_size, crop_mode) preset. An unrecognized mode string — after strip/lower normalization — logs the supported list and raises ValueError. The supported set is fixed by _IMAGE_MODE_PRESETS.

Source

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

    "base": (1024, 1024, False),
    "large": (1280, 1280, False),
    "gundam": (1024, 640, True),
}
_DEFAULT_MODE = "gundam"


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]

View on GitHub (pinned to 0132848349)

Solutions

1. Use one of the presets printed in the error (from _IMAGE_MODE_PRESETS keys, e.g. tiny/small/base)
2. Omit image_mode to use the default
3. Upgrade sglang if docs mention a mode your version lacks

Example fix

# before
processor.process_mm_data_async(..., image_mode='high')
# after
processor.process_mm_data_async(..., image_mode='base')

SUPPORTED = {'tiny', 'small', 'base'}  # from _IMAGE_MODE_PRESETS
if image_mode.strip().lower() not in SUPPORTED:
    raise ValueError(f'image_mode must be one of {SUPPORTED}')

When it happens

Trigger: Passing image_mode like 'high', 'hd', 'auto', or a misspelled preset ('Bas') to the processor's process_mm_data_async; the key lookup in _IMAGE_MODE_PRESETS returns None.

Common situations: Copy-pasting image_mode values from other models' APIs (e.g. Qwen-VL 'high'/'low'); passing extra flags like 'max' expecting resolution tiers; version drift where presets were renamed.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• image_mode='{mode}' is not supported with multiple images (g
• 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',
• Invalid quantization choice: '{quant_choice_str}'. Available

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