sgl-project/sglang · error · ValueError

Unsupported layout: {self.layout}

Error message

Unsupported layout: {self.layout}

What it means

The host DSA indexer pool allocates its index buffer with one of two memory layouts, 'layer_first' or 'page_first'. init_kv_buffer raises this when self.layout is neither. It is a configuration/state error, not runtime data dependent.

Source

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

                [x.data_ptr() for x in self.index_k_data_refs],
                dtype=torch.uint64,
                device=self.device_pool.device,
            )
        elif self.layout in ["page_first", "page_first_direct"]:
            self.index_k_with_scale_buffer = alloc_func(
                (
                    self.indexer_page_num,
                    self.layer_num,
                    1,
                    self.indexer_page_stride_size,
                ),
                dtype=self.indexer_dtype,
                device=self.device,
                pin_memory=self.pin_memory,
                allocator=self.allocator,
            )
        else:
            raise ValueError(f"Unsupported layout: {self.layout}")

    def _init_write_back_staging_buffers(self):
        self.staging_buffer = None
        if self.layout != "page_first" or (_is_npu or _is_xpu or _is_mps):
            return

        self.can_use_write_back_jit = _is_cuda and can_use_write_back_jit_kernel(
            element_size=self.indexer_page_stride_size * self.indexer_dtype.itemsize,
        )
        staging_page_capacity = min(
            self.indexer_page_num, _WRITE_BACK_STAGING_PAGE_CHUNK
        )
        self.staging_buffer = torch.empty(
            (
                staging_page_capacity,
                self.layer_num,
                1,
                self.indexer_page_stride_size,

View on GitHub (pinned to 0132848349)

Solutions

1. Set layout to exactly 'layer_first' or 'page_first'
2. Check where the layout string originates (server args / config) and correct it
3. Note page_first has extra restrictions (see staging buffer, NPU/XPU/MPS exclusion)

Example fix

# before
layout="layers_first"
# after
layout="layer_first"

assert layout in ("layer_first", "page_first"), layout

def is_valid_dsa_layout(l: str) -> bool:
    return l in ("layer_first", "page_first")

When it happens

Trigger: Passing a layout string other than 'layer_first' or 'page_first' (typo, wrong case, or a new unsupported value) to the DSA host pool constructor.

Common situations: Typos in config, case mismatch ('LayerFirst'), or code written against a fork that added a layout not present in this version.

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 IO backend: {io_backend}
• Layer-sharded DSA indexer HiCache backup with page_first lay
• 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

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