{"record":{"id":"593494569ce62bc4","repo":"sgl-project/sglang","slug":"unsupported-layout-self-layout-593494","errorCode":null,"errorMessage":"Unsupported layout: {self.layout}","messagePattern":"Unsupported layout: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/mem_cache/pool_host/mha.py","lineNumber":186,"sourceCode":"            dims = (\n                2,\n                self.page_num,\n                self.layer_num,\n                self.page_size,\n                self.head_num,\n                self.head_dim,\n            )\n        elif self.layout == \"page_head\":\n            dims = (\n                2,\n                self.page_num,\n                self.head_num,\n                self.page_size,\n                self.layer_num,\n                self.head_dim,\n            )\n        else:\n            raise ValueError(f\"Unsupported layout: {self.layout}\")\n        self.token_stride_size = self.head_num * self.head_dim * self.dtype.itemsize\n        self.layout_dim = self.token_stride_size * self.layer_num\n\n        alloc_func = ALLOC_MEMORY_FUNCS[self.device_pool.device]\n        buffer = alloc_func(\n            dims,\n            dtype=self.dtype,\n            device=self.device,\n            pin_memory=self.pin_memory,\n            allocator=self.allocator,\n        )\n        return buffer\n\n    def _init_write_back_staging_buffers(self):\n        self.staging_page_capacity = 0\n        self.staging_token_capacity = 0\n        self.staging_k_buffer = None\n        self.staging_v_buffer = None","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/pool_host/mha.py#L168-L204","documentation":"The MHA host KV pool allocates its host-side buffer with a shape that depends on the storage layout; init_kv_buffer only knows how to build dims for implemented layouts (layer_first and page-first variants). An unknown layout string means no valid buffer shape can be computed, so construction fails.","triggerScenarios":"Instantiating the MHA host pool (HierarchicalCache host KV buffer) with self.layout set to anything other than 'layer_first' / 'page_first' / 'page_first_direct' — e.g. a typo in the layout argument or a new layout value not handled at init.","commonSituations":"Custom ServerArgs / hierarchical-cache config passing a misspelled layout; code forks that introduce a new layout without updating init_kv_buffer; version mismatch where a layout constant was renamed.","solutions":["Print/inspect the layout string passed to the host pool constructor and fix it to one of the supported values ('layer_first', 'page_first', 'page_first_direct')","Do not set host KV layout manually unless needed; let SGLang derive it from server_args","If you added a new layout, extend init_kv_buffer with the corresponding dims construction (mirror the layer_first branch)","Upgrade SGLang / align fork with upstream layout constants"],"exampleFix":"# before\npool = MHAHostPool(..., layout=\"pagefirst\")\n# after\npool = MHAHostPool(..., layout=\"page_first\")","handlingStrategy":"validation","validationCode":"SUPPORTED_LAYOUTS = (\"layer_first\", \"page_first\", \"page_first_direct\")\nassert layout in SUPPORTED_LAYOUTS, f\"unsupported host pool layout: {layout!r}\"","typeGuard":"def is_supported_layout(layout: str) -> bool:\n    return layout in (\"layer_first\", \"page_first\", \"page_first_direct\")","tryCatchPattern":null,"preventionTips":["Never hand-type layout strings; import/reuse constants from sglang","Let ServerArgs derive the layout automatically","Validate layout at config load time, fail fast before model launch"],"tags":["sglang","kv-cache","layout","host-pool","initialization"],"backgroundTag":"unsupported-layout-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}