{"record":{"id":"bbba937c54afad3c","repo":"sgl-project/sglang","slug":"unsupported-layout-for-models-with-head-dim-v-h-bbba93","errorCode":null,"errorMessage":"Unsupported layout for models with head_dim != v_head_dim: {self.layout}","messagePattern":"Unsupported layout for models with head_dim != v_head_dim: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/mem_cache/pool_host/mha.py","lineNumber":1319,"sourceCode":"\n    def get_dummy_flat_data_page(self) -> torch.Tensor:\n        raise self._flat_page_unsupported()\n\n    def set_from_flat_data_page(self, index: int, data_page: torch.Tensor) -> None:\n        raise self._flat_page_unsupported()\n\n    def get_split_heads_page_buffer_meta(\n        self, indices: torch.Tensor, split_factor: int\n    ):\n        raise NotImplementedError(\n            \"get_split_heads_page_buffer_meta requires layout='page_head', \"\n            \"which is not supported for models with head_dim != v_head_dim.\"\n        )\n\n    def get_page_buffer_meta(self, indices):\n        assert len(indices) % self.page_size == 0\n        if self.layout not in (\"page_first\", \"page_first_direct\"):\n            raise ValueError(\n                f\"Unsupported layout for models with head_dim != v_head_dim: \"\n                f\"{self.layout}\"\n            )\n        indices = indices.tolist()\n        k_base_ptr = self.k_buffer.data_ptr()\n        v_base_ptr = self.v_buffer.data_ptr()\n        k_element_size = (\n            self.layer_num\n            * self.dtype.itemsize\n            * self.page_size\n            * self.head_num\n            * self.head_dim\n        )\n        v_element_size = (\n            self.layer_num\n            * self.dtype.itemsize\n            * self.page_size\n            * self.head_num","sourceCodeStart":1301,"sourceCodeEnd":1337,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/pool_host/mha.py#L1301-L1337","documentation":"get_page_buffer_meta on the head_dim != v_head_dim MHA host pool only supports 'page_first' and 'page_first_direct' layouts. The pool was constructed with some other layout (e.g. 'layer_first' or 'page_head'), so page-buffer metadata cannot be computed.","triggerScenarios":"Calling get_page_buffer_meta(indices) when self.layout is not 'page_first' or 'page_first_direct'.","commonSituations":"HiCache configured with a layer-first host layout (common on some backends) while code needs page-buffer meta for zero-copy page transfers; version changes altering default layout.","solutions":["Construct the host pool with layout='page_first' (or 'page_first_direct')","Check the server arg / pool allocator that selects layout and align it","Avoid calling get_page_buffer_meta for layer-first pools; use the per-layer transfer APIs instead"],"exampleFix":"// before\nMHATokenToKVPoolHost(..., layout=\"layer_first\")  # later: pool.get_page_buffer_meta(idx) fails\n\n// after\nMHATokenToKVPoolHost(..., layout=\"page_first\")","handlingStrategy":"validation","validationCode":"if pool.layout not in (\"page_first\", \"page_first_direct\"):\n    raise ConfigError(f\"page-buffer meta requires page_first layouts, got {pool.layout}\")","typeGuard":"def has_page_buffer_meta(pool) -> bool:\n    return getattr(pool, \"layout\", None) in (\"page_first\", \"page_first_direct\")","tryCatchPattern":"try:\n    meta = pool.get_page_buffer_meta(indices)\nexcept ValueError as e:\n    if \"Unsupported layout\" in str(e):\n        meta = None  # use per-layer transfer APIs instead\n    else:\n        raise","preventionTips":["Choose page_first layout when zero-copy page transfers are needed","Assert layout invariants right after pool construction"],"tags":["sglang","hicache","layout","kv-cache"],"backgroundTag":"unsupported-layout-combination","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}