sgl-project/sglang · error · ValueError

Unsupported Kimi-K3 deferred preprocessing backend: {backend

Error message

Unsupported Kimi-K3 deferred preprocessing backend: {backend}

What it means

materialize_item_features() dispatches deferred preprocessing only to 'gpu' and 'cpu' backends; any other value in the deferred config's backend field raises ValueError. The backend string comes from the per-item deferred preprocessing config.

Source

Thrown at python/sglang/srt/models/kimi_k3.py:3473

                            post_resize=lambda x: fill_transparent_bg(
                                x, first_config.transparent_bg_config
                            ),
                        )
                        expected_grids = grid_thws_host[global_indices]
                        if not torch.equal(produced_grids.cpu(), expected_grids):
                            raise ValueError(
                                "Kimi-K3 deferred GPU preprocessing produced wrong grids"
                            )
                    elif backend == "cpu":
                        from sglang.srt.multimodal.kimi_k3_image_processing import (
                            materialize_kimi_k3_cpu_features,
                        )

                        pixel_values = materialize_kimi_k3_cpu_features(
                            group_items, self._encoder_image_processor
                        )
                    else:
                        raise ValueError(
                            f"Unsupported Kimi-K3 deferred preprocessing backend: {backend}"
                        )

                    patch_counts = [
                        int(grid_thws_host[index].prod().item())
                        for index in global_indices
                    ]
                    if sum(patch_counts) != pixel_values.shape[0]:
                        raise ValueError(
                            "Kimi-K3 deferred feature length does not match image grids"
                        )
                    for index, feature in zip(
                        indices, pixel_values.split(patch_counts), strict=True
                    ):
                        materialized[index] = feature

                return materialize_multimodal_features(
                    materialized,

View on GitHub (pinned to 0132848349)

Solutions

Set backend to 'gpu' or 'cpu' explicitly in the deferred preprocessing config
Validate backend values at config construction time against {'gpu','cpu'}
Sync any fork-specific backend names with upstream constants

Example fix

// before
cfg.backend = "cuda"  # unsupported

// after
cfg.backend = "gpu"

Defensive patterns

Strategy: validation

Validate before calling

assert cfg.backend in {"gpu", "cpu"}, f"unsupported backend {cfg.backend}"

Type guard

def is_supported_backend(b) -> bool:
    return b in {"gpu", "cpu"}

Try / catch

try:
    model.get_image_feature(items)
except ValueError as e:
    if "backend" in str(e):
        cfg.backend = "cpu"
        return model.get_image_feature(items)
    raise

Prevention

Construct deferred configs from constants, not raw strings
Validate backend at config creation and fail early with a clear message

When it happens

Trigger: A deferred config with backend set to something other than 'gpu' or 'cpu' (typo, renamed constant, or new unsupported backend) reaching the dispatch in get_image_feature().

Common situations: Custom preprocessing configs introduced by a fork or newer config format; enum/constant renamed between versions so the stored backend string no longer matches.

Related errors

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