sgl-project/sglang · error · ValueError

Unsupported layout: {self.layout}

Error message

Unsupported layout: {self.layout}

What it means

The V4 paged host pool's __init__ dispatches tensor allocation on self.layout and only supports a fixed set (layer_first / page_first / page_first_direct variants). Any other layout string reaches the else branch and raises ValueError 'Unsupported layout'.

Source

Thrown at python/sglang/srt/mem_cache/memory_pool_host.py:249

            self.data_refs = [self.kv_buffer[i] for i in range(self.layer_num)]
        elif self.layout == "page_first":
            self.kv_buffer = alloc_func(
                (num_host_pages, self.layer_num, self.item_bytes),
                dtype=self.dtype,
                device=self.device,
                pin_memory=self.pin_memory,
                allocator=self.allocator,
            )
        elif self.layout == "page_first_direct":
            self.kv_buffer = alloc_func(
                (num_host_pages, self.layer_num, 1, self.item_bytes),
                dtype=self.dtype,
                device=self.device,
                pin_memory=self.pin_memory,
                allocator=self.allocator,
            )
        else:
            raise ValueError(f"Unsupported layout: {self.layout}")

        logger.info(
            "Allocating %.2f GB host memory for V4 paged pool '%s' "
            "(layers=%d, pages=%d, item_bytes=%d, layout=%s).",
            requested_bytes / 1e9,
            self.pool_name,
            self.layer_num,
            num_host_pages,
            self.item_bytes,
            self.layout,
        )

        self.device_ptrs = torch.tensor(
            [x.data_ptr() for x in self.device_buffers],
            dtype=torch.uint64,
            device=self.gpu_device,
        )
        self.data_ptrs = (

View on GitHub (pinned to 0132848349)

Solutions

1. Use one of the supported layout strings exactly as implemented (check the if/elif branches in memory_pool_host.py)
2. Fix typos/normalization in whatever code produces the layout string
3. If adding a new layout, implement its allocation branch and mirror it in get_data_page/set_from_flat_data_page/get_page_buffer_meta which have parallel switches

Example fix

# before
pool = V4PagedHostPool(..., layout="page-first")  # typo

# after
pool = V4PagedHostPool(..., layout="page_first")

assert layout in {"layer_first", "page_first", "page_first_direct"}, f"unknown layout {layout}"

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

try:
    pool = V4PagedHostPool(..., layout=layout)
except ValueError as e:
    raise ValueError(f"bad layout {layout!r}: {e}") from e

When it happens

Trigger: Passing layout=... with an unrecognized value (typo like 'page-first', or a new layout name not implemented) when constructing the pool.

Common situations: Custom backend code introducing a new host layout without updating the constructor switch; typos in config strings; version drift where a layout name changed between SGLang releases.

Related errors

• f"SGLang KDA state must be [B,H,V,K] with (V,K)={expected},
• NVIDIA KDA state must be [B,H,K,V] with (K,V)={expected}, go
• LoRA adapter {lora_ref.lora_name} with rank {lora_config.r}
• LogicalHostPool size must be page-aligned, got size={size},
• LogicalHostPool allocation must be page-aligned, got need_si

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