{"record":{"id":"6a39c170a60831fb","repo":"sgl-project/sglang","slug":"layer-sharded-dsa-indexer-hicache-backup-with-page","errorCode":null,"errorMessage":"Layer-sharded DSA indexer HiCache backup with page_first layout is not supported without a per-layer LF->PF kernel.","messagePattern":"Layer-sharded DSA indexer HiCache backup with page_first layout is not supported without a per-layer LF->PF kernel\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/mem_cache/pool_host/dsa.py","lineNumber":312,"sourceCode":"        # MTP draft layers do not participate in CP layer sharding.\n        host_layer_id = layer_id if is_draft else self._host_layer_index(layer_id)\n        device_layer_id = 0 if is_draft else layer_id\n\n        host_page_indices, device_page_indices = self._get_indexer_page_indices(\n            host_indices, device_indices\n        )\n        use_kernel = io_backend == \"kernel\" and self.indexer_page_stride_size % 8 == 0\n        if use_kernel:\n            if self.layout == \"layer_first\":\n                transfer_kv_per_layer_mla(\n                    src=device_pool.index_k_with_scale_buffer[device_layer_id],\n                    dst=self.index_k_with_scale_buffer[host_layer_id],\n                    src_indices=device_page_indices,\n                    dst_indices=host_page_indices,\n                    item_size=self.indexer_page_stride_size,\n                )\n            elif self.layout == \"page_first\":\n                raise ValueError(\n                    \"Layer-sharded DSA indexer HiCache backup with page_first \"\n                    \"layout is not supported without a per-layer LF->PF kernel.\"\n                )\n            else:\n                raise ValueError(f\"Unsupported layout: {self.layout}\")\n        elif io_backend == \"direct\":\n            if self.layout == \"layer_first\":\n                transfer_kv_direct(\n                    src_layers=[device_pool.index_k_with_scale_buffer[device_layer_id]],\n                    dst_layers=[self.index_k_with_scale_buffer[host_layer_id]],\n                    src_indices=device_page_indices,\n                    dst_indices=host_page_indices,\n                    page_size=1,\n                )\n            else:\n                raise ValueError(\n                    \"Layer-sharded direct DSA indexer backup only supports \"\n                    f\"layer_first layout, got {self.layout}\"","sourceCodeStart":294,"sourceCodeEnd":330,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/pool_host/dsa.py#L294-L330","documentation":"Backing up (device->host) a layer-sharded DSA indexer per-layer with page_first layout would require converting layer-first device data to page-first host layout per layer, and no such kernel exists, so the operation is explicitly rejected.","triggerScenarios":"backup_from_device_all_layer on a layer-sharded device pool where layout='page_first', with the kernel IO backend.","commonSituations":"Enabling layer sharding (e.g. PP/layer-parallel device pools) together with page_first host layout and hierarchical cache backup.","solutions":["Switch host layout to 'layer_first'","Or avoid layer-sharded device pools with the DSA HiCache backup path","Track upstream for a per-layer LF->PF kernel"],"exampleFix":"# before\nlayout='page_first'  # + layer-sharded device pool\n# after\nlayout='layer_first'","handlingStrategy":"type-guard","validationCode":"if layer_sharded and io_backend == \"kernel\":\n    assert layout == \"layer_first\"","typeGuard":"def sharded_backup_supported(layout: str, io_backend: str) -> bool:\n    return layout == \"layer_first\"","tryCatchPattern":null,"preventionTips":["Avoid page_first layout with layer-sharded device pools when HiCache backup is enabled"],"tags":["dsa-hicache","layout","layer-sharding"],"backgroundTag":"unsupported-feature-combination","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}