sgl-project/sglang · error · ValueError

Unsupported image processor backend

Error message

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

What it means

Image processor backend selection error: the configured backend string is not among the supported backends (list included in the message). Set the backend to one of the listed values (e.g. HF / custom processor variants).

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
Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

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


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

Appendix: 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)