sgl-project/sglang · error · ValueError

Unsupported image processor backend: {backend}. Expected one

Error message

Unsupported image processor backend: {backend}. Expected one of {sorted(_IMAGE_PROCESSOR_BACKENDS)}.

What it means

The image processor backend string passed via image_processor_backend (or resolved to 'auto' default) is not in the supported set _IMAGE_PROCESSOR_BACKENDS. The message lists valid backend names.

Source

Thrown at python/sglang/srt/utils/hf_transformers/processor.py:74

def resolve_image_processor_backend(mm_config) -> str:
    """Resolve the new backend option while honoring the legacy disable flag.

    Takes the `mm` config bag (`get_mm()`): both leaves are resolved config, and
    every caller is past publish. `getattr` with a default keeps it working for a
    stand-in that carries only one of the two.
    """
    if getattr(mm_config, "disable_fast_image_processor", False):
        return "pil"
    return getattr(mm_config, "image_processor_backend", "auto")


def _normalize_image_processor_backend(
    image_processor_backend: Optional[str], use_fast: Optional[bool]
) -> str:
    backend = image_processor_backend or "auto"
    if backend not in _IMAGE_PROCESSOR_BACKENDS:
        raise ValueError(
            f"Unsupported image processor backend: {backend}. "
            f"Expected one of {sorted(_IMAGE_PROCESSOR_BACKENDS)}."
        )

    if use_fast is not None:
        legacy_backend = "torchvision" if use_fast else "pil"
        if backend not in {"auto", legacy_backend}:
            raise ValueError(
                f"use_fast={use_fast} conflicts with "
                f"image_processor_backend={backend!r}."
            )
        backend = legacy_backend
    return backend


def _apply_image_processor_backend(
    processor,
    tokenizer_name,

View on GitHub (pinned to 0132848349)

Solutions

1. Use one of the backends listed in the error message (typically auto, pil, torchvision)
2. Check the flag spelling and casing against the current sglang docs
3. Upgrade sglang if you expected a newly added backend

Example fix

# before
--image-processor-backend tensor
# after
--image-processor-backend torchvision

assert backend in {'auto','pil','torchvision'}, f'bad backend {backend}'

When it happens

Trigger: Passing --image-processor-backend with a typo or unsupported value, e.g. 'tensor' instead of 'torchvision', 'PIL', or 'flash' style names.

Common situations: Copy-pasting backend names from other frameworks (vLLM-style flags) into sglang, or using a value removed in a newer release.

Related errors

• mm_preprocess_cache_size_mb must be non-negative
• mm_process_config must be a dict, but got {type(cfg.mm_proce
• mm_process_config['{key}'] must be a dict, but got {type(cfg
• Invalid modality '{modality}' in --limit-mm-data-per-request
• use_fast={use_fast} conflicts with image_processor_backend={

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