{"record":{"id":"73fbed350272644f","repo":"sgl-project/sglang","slug":"page-major-layout-has-no-per-layer-contiguous-regi","errorCode":null,"errorMessage":"page-major layout has no per-layer contiguous regions; KV transfer / disaggregation is unsupported (TODO: expose the single _raw buffer with a page-aware transfer scheme).","messagePattern":"page-major layout has no per-layer contiguous regions; KV transfer / disaggregation is unsupported \\(TODO: expose the single _raw buffer with a page-aware transfer scheme\\)\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/mem_cache/memory_pool.py","lineNumber":3313,"sourceCode":"    def _move_kv_cache_impl(self, tgt_loc: torch.Tensor, src_loc: torch.Tensor):\n        # Strided 4-D views: the tiled copy kernel assumes stride == row bytes, so\n        # always take the native move (it splits token ids into\n        # (page_id, slot_in_page) for the 4-D advanced index).\n        move_kv_cache_native(\n            self.k_buffer,\n            self.v_buffer,\n            tgt_loc,\n            src_loc,\n            page_size=self.page_size,\n        )\n\n    # The methods below assume the per-layer contiguous 3-D layout. The 4-D\n    # strided envelope views have no per-layer contiguous region (their bytes are\n    # interleaved layer-major within each page) and index page-major, not\n    # token-major. Inheriting them would silently mis-index; fail loudly instead.\n\n    def get_contiguous_buf_infos(self):\n        raise NotImplementedError(\n            \"page-major layout has no per-layer contiguous regions; KV transfer / \"\n            \"disaggregation is unsupported (TODO: expose the single _raw buffer \"\n            \"with a page-aware transfer scheme).\"\n        )\n\n    def get_cpu_copy(self, indices, mamba_indices=None):\n        raise NotImplementedError(\n            \"CPU offloading is unsupported under the page-major layout \"\n            \"(TODO: split token ids into page/slot for the 4-D index).\"\n        )\n\n    def load_cpu_copy(self, kv_cache_cpu, indices, mamba_indices=None):\n        raise NotImplementedError(\n            \"CPU offloading is unsupported under the page-major layout \"\n            \"(TODO: split token ids into page/slot for the 4-D index).\"\n        )\n\n    def set_kv_buffer_prefix_valid(self, *args, **kwargs):","sourceCodeStart":3295,"sourceCodeEnd":3331,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/memory_pool.py#L3295-L3331","documentation":"The page-major (4-D strided envelope) KV pool layout stores KV bytes interleaved layer-major within each page, so there is no per-layer contiguous 3-D region. Methods like get_contiguous_buf_infos assume that contiguous layout for KV transfer/disaggregation, so they raise NotImplementedError instead of silently mis-indexing.","triggerScenarios":"Enabling the page-major KV layout (page size > 1 with the strided 4-D buffer allocation) and then invoking get_contiguous_buf_infos, e.g. by starting a PD-disaggregation or KV transfer (cache transfer) flow on top of that pool.","commonSituations":"Turning on page-size/paged KV layout together with --disaggregation or any prefill-decode transfer feature; new code paths calling get_contiguous_buf_infos for transfer initialization.","solutions":["Disable the page-major layout (fall back to page_size=1 / token-major 3-D pool) when disaggregation or KV transfer is needed","Disable disaggregation / KV transfer features if the page-major layout is required","Wait for / implement the page-aware transfer scheme over the single _raw buffer mentioned in the TODO"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"def can_disaggregate(pool) -> bool:\n    try:\n        pool.get_contiguous_buf_infos()\n        return True\n    except NotImplementedError:\n        return False","typeGuard":"def is_page_major_pool(pool) -> bool:\n    return hasattr(pool, '_raw') and getattr(pool, 'page_size', 1) > 1","tryCatchPattern":"try:\n    infos = pool.get_contiguous_buf_infos()\nexcept NotImplementedError as e:\n    logger.warning('KV transfer unsupported for %s: %s', type(pool).__name__, e)\n    raise","preventionTips":["Add a startup capability check when disaggregation args are set","Document feature-compatibility matrix for page-major layout","Gate disaggregation flags on pool type in server_args validation"],"tags":["kv-cache","page-major","disaggregation","not-implemented"],"backgroundTag":"unsupported-feature-combination","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}