sgl-project/sglang · error · ValueError

Unsupported layout: {self.layout}

Error message

Unsupported layout: {self.layout}

What it means

The MLA host KV pool's init_kv_buffer hit a layout branch it does not recognize, so it cannot allocate the host kv_buffer. Supported MLA layouts include 'layer_first', 'page_first', 'page_first_kv_split', and the Ascend special case; anything else raises this ValueError.

Source

Thrown at python/sglang/srt/mem_cache/pool_host/mla.py:198

                dtype=self.dtype,
                device=self.device,
                pin_memory=self.pin_memory,
                allocator=self.allocator,
            )
            self.index_k_buffer = None
            if self.device_pool.index_head_dim is not None:
                self.index_k_buffer = alloc_func(
                    (*base_dims, self.device_pool.index_head_dim),
                    dtype=self.dtype,
                    device=self.device,
                    pin_memory=self.pin_memory,
                    allocator=self.allocator,
                )
            # Return k_buffer to preserve original kv_buffer and data_refs init logic,
            # though Ascend doesn't use these parameters.
            return self.k_buffer
        else:
            raise ValueError(f"Unsupported layout: {self.layout}")
        self.token_stride_size = self.kv_cache_dim * self.dtype.itemsize
        self.layout_dim = self.token_stride_size * self.layer_num

        alloc_func = ALLOC_MEMORY_FUNCS[self.device_pool.device]
        buffer = alloc_func(
            dims,
            dtype=self.dtype,
            device=self.device,
            pin_memory=self.pin_memory,
            allocator=self.allocator,
        )
        return buffer

    def _init_write_back_staging_buffers(self):
        self.staging_page_capacity = 0
        self.staging_token_capacity = 0
        self.staging_buffer = None
        self.can_use_write_back_jit = False

View on GitHub (pinned to 0132848349)

Solutions

1. Check the value passed for layout and correct it to a supported name ('layer_first', 'page_first', 'page_first_kv_split')
2. Update sglang so caller and pool agree on layout names
3. Add an upfront validation/enum for layout values before pool construction

Example fix

// before
MLATokenToKVPoolHost(..., layout="layer-first")

// after
MLATokenToKVPoolHost(..., layout="layer_first")

MLA_HOST_LAYOUTS = {"layer_first", "page_first", "page_first_kv_split"}
if layout not in MLA_HOST_LAYOUTS:
    raise ConfigError(f"layout must be one of {MLA_HOST_LAYOUTS}, got {layout!r}")

def is_valid_mla_layout(layout: str) -> bool:
    return layout in {"layer_first", "page_first", "page_first_kv_split"}

try:
    pool = MLATokenToKVPoolHost(..., layout=layout)
except ValueError as e:
    if "Unsupported layout" in str(e):
        layout = "layer_first"  # safe default
        pool = MLATokenToKVPoolHost(..., layout=layout)
    else:
        raise

When it happens

Trigger: Constructing the MLA host pool with a layout string outside the supported set (typo like 'layer-first' or a new/renamed layout value).

Common situations: Renaming or introducing layouts without updating this branch; passing a custom layout from server args; version mismatch where the caller uses a layout name that this build does not know.

Related errors

• Unsupported layout for models with head_dim != v_head_dim an
• Unsupported layout for models with head_dim != v_head_dim an
• Layer-sharded HiCache backup does not support layout: {self.
• Unsupported V4 paged host layout/backend: {self.layout}/{io_
• Unsupported layout for models with head_dim != v_head_dim: {

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