sgl-project/sglang · error · ValueError

Unsupported IO backend: {io_backend}

Error message

Unsupported IO backend: {io_backend}

What it means

load_to_device_per_layer dispatches on io_backend and only implements 'kernel' and 'direct'. Any other string reaches this raise.

Source

Thrown at python/sglang/srt/mem_cache/pool_host/dsa.py:282

                    src_layers=[self.index_k_with_scale_buffer[host_layer_id]],
                    dst_layers=[device_pool.index_k_with_scale_buffer[device_layer_id]],
                    src_indices=host_page_indices,
                    dst_indices=device_page_indices,
                    page_size=1,
                )
            elif self.layout == "page_first_direct":
                transfer_kv_per_layer_direct_pf_lf(
                    src_ptrs=[self.index_k_with_scale_buffer],
                    dst_ptrs=[device_pool.index_k_with_scale_buffer[device_layer_id]],
                    src_indices=host_page_indices,
                    dst_indices=device_page_indices,
                    layer_id=host_layer_id,
                    page_size=1,
                )
            else:
                raise ValueError(f"Unsupported layout: {self.layout}")
        else:
            raise ValueError(f"Unsupported IO backend: {io_backend}")

    def _backup_from_device_per_layer(
        self,
        device_pool,
        host_indices,
        device_indices,
        layer_id,
        io_backend,
        *,
        is_draft: bool = False,
    ):
        # MTP draft layers do not participate in CP layer sharding.
        host_layer_id = layer_id if is_draft else self._host_layer_index(layer_id)
        device_layer_id = 0 if is_draft else layer_id

        host_page_indices, device_page_indices = self._get_indexer_page_indices(
            host_indices, device_indices
        )

View on GitHub (pinned to 0132848349)

Solutions

1. Use io_backend='kernel' or 'direct'
2. Trace where io_backend is set (server args / HiCache config) and fix the value

Example fix

# before
io_backend='cuda'
# after
io_backend='direct'

assert io_backend in ("kernel", "direct"), io_backend

def is_valid_io_backend(b: str) -> bool:
    return b in ("kernel", "direct")

When it happens

Trigger: Passing io_backend other than 'kernel' or 'direct' (typo, 'cuda', 'io_uring', None) to load_to_device_per_layer.

Common situations: Config typos or code written for a different backend naming scheme; a None default leaking from an unset config.

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

• Unsupported layout: {self.layout}
• Layer-sharded direct DSA indexer backup only supports layer_
• This browser cannot encode H.264 MP4
• H.264 encoder did not return MP4 decoder config
• This browser does not support gzip stream decoding

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