{"record":{"id":"2a225ebcabb0f651","repo":"sgl-project/sglang","slug":"unsupported-layout-self-layout","errorCode":null,"errorMessage":"Unsupported layout: {self.layout}","messagePattern":"Unsupported layout: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/mem_cache/memory_pool_host.py","lineNumber":249,"sourceCode":"            self.data_refs = [self.kv_buffer[i] for i in range(self.layer_num)]\n        elif self.layout == \"page_first\":\n            self.kv_buffer = alloc_func(\n                (num_host_pages, self.layer_num, self.item_bytes),\n                dtype=self.dtype,\n                device=self.device,\n                pin_memory=self.pin_memory,\n                allocator=self.allocator,\n            )\n        elif self.layout == \"page_first_direct\":\n            self.kv_buffer = alloc_func(\n                (num_host_pages, self.layer_num, 1, self.item_bytes),\n                dtype=self.dtype,\n                device=self.device,\n                pin_memory=self.pin_memory,\n                allocator=self.allocator,\n            )\n        else:\n            raise ValueError(f\"Unsupported layout: {self.layout}\")\n\n        logger.info(\n            \"Allocating %.2f GB host memory for V4 paged pool '%s' \"\n            \"(layers=%d, pages=%d, item_bytes=%d, layout=%s).\",\n            requested_bytes / 1e9,\n            self.pool_name,\n            self.layer_num,\n            num_host_pages,\n            self.item_bytes,\n            self.layout,\n        )\n\n        self.device_ptrs = torch.tensor(\n            [x.data_ptr() for x in self.device_buffers],\n            dtype=torch.uint64,\n            device=self.gpu_device,\n        )\n        self.data_ptrs = (","sourceCodeStart":231,"sourceCodeEnd":267,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/memory_pool_host.py#L231-L267","documentation":"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'.","triggerScenarios":"Passing layout=... with an unrecognized value (typo like 'page-first', or a new layout name not implemented) when constructing the pool.","commonSituations":"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.","solutions":["Use one of the supported layout strings exactly as implemented (check the if/elif branches in memory_pool_host.py)","Fix typos/normalization in whatever code produces the layout string","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"],"exampleFix":"# before\npool = V4PagedHostPool(..., layout=\"page-first\")  # typo\n\n# after\npool = V4PagedHostPool(..., layout=\"page_first\")","handlingStrategy":"type-guard","validationCode":"assert layout in {\"layer_first\", \"page_first\", \"page_first_direct\"}, f\"unknown layout {layout}\"","typeGuard":"def is_supported_layout(layout: str) -> bool:\n    return layout in {\"layer_first\", \"page_first\", \"page_first_direct\"}","tryCatchPattern":"try:\n    pool = V4PagedHostPool(..., layout=layout)\nexcept ValueError as e:\n    raise ValueError(f\"bad layout {layout!r}: {e}\") from e","preventionTips":["Define layout constants instead of raw strings","Validate layout once at config parse time","Add the new layout to every dispatch switch if you extend layouts"],"tags":["sglang","memory-pool","layout","invalid-config"],"backgroundTag":"unsupported-layout-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}