{"record":{"id":"71772120f73c35c9","repo":"sgl-project/sglang","slug":"dsv4-hisparse-direct-pd-transfer-currently-require","errorCode":null,"errorMessage":"DSV4 HiSparse direct PD transfer currently requires the Mooncake backend","messagePattern":"DSV4 HiSparse direct PD transfer currently requires the Mooncake backend","errorType":"validation","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/disaggregation/decode.py","lineNumber":1492,"sourceCode":"            if (\n                self.scheduler.enable_hisparse\n                and isinstance(self.token_to_kv_pool, DeepSeekV4TokenToKVPool)\n                and not _is_fake_transfer(decode_req.req)\n            ):\n                # alloc_logical_only() already allocated the shared logical pages\n                # used by C4 indexer and C128 KV. These device buffers do not use\n                # the C4 sparse physical-slot mapping; carry their logical page IDs\n                # alongside the independently allocated C4 host page IDs.\n                full_kv_indices = self.req_to_token_pool.req_to_token[\n                    decode_req.req.req_pool_idx,\n                    prefix_len:origin_input_len,\n                ]\n                device_page_indices = kv_to_page_indices(\n                    full_kv_indices,\n                    page_size,\n                ).astype(np.int32)\n                if self.transfer_backend != TransferBackend.MOONCAKE:\n                    raise NotImplementedError(\n                        \"DSV4 HiSparse direct PD transfer currently requires \"\n                        \"the Mooncake backend\"\n                    )\n            metadata_kwargs = {\"decode_prefix_len\": total_prefix_len}\n            if device_page_indices is not None:\n                metadata_kwargs[\"device_kv_indices\"] = device_page_indices\n            if (\n                self.transfer_queue.enable_staging\n                and hasattr(decode_req.kv_receiver, \"require_staging\")\n                and decode_req.kv_receiver.require_staging\n            ):\n                # Register before send_metadata, which triggers the STAGING_REQ\n                # prefetch (dropped for an unregistered room); tiny race, correct order.\n                self.transfer_queue.staging_handler.register_decode_req(\n                    decode_req.req.bootstrap_room, decode_req\n                )\n            decode_req.kv_receiver.send_metadata(\n                page_indices,","sourceCodeStart":1474,"sourceCodeEnd":1510,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/disaggregation/decode.py#L1474-L1510","documentation":"While popping preallocated requests, the DSV4 (DeepSeek-V4) HiSparse direct PD transfer path builds device_kv_indices and only supports the Mooncake transfer backend; any other backend raises NotImplementedError. HiSparse requires Mooncake's device-side transfer API to move KV directly without host staging.","triggerScenarios":"Running a DSV4/HiSparse model in PD disaggregation with --disaggregation-transfer-backend set to something other than mooncake (e.g. nixl or fake) while the direct transfer path is taken in pop_preallocated.","commonSituations":"Reusing an existing NIXL-based PD deployment config for a new HiSparse model; defaulting to a non-Mooncake backend and upgrading to a DSV4 model.","solutions":["Set --disaggregation-transfer-backend mooncake for DSV4 HiSparse PD deployments","Ensure a compatible Mooncake version with device transfer support is installed (sgl-kernel/mooncake packages)","If Mooncake is unavailable in your environment, disable the HiSparse direct path or use a supported model until support lands"],"exampleFix":"# before\n--disaggregation-transfer-backend nixl  # DSV4 HiSparse\n# after\n--disaggregation-transfer-backend mooncake","handlingStrategy":"validation","validationCode":"if is_dsv4_hisparse(model_path):\n    assert transfer_backend == TransferBackend.MOONCAKE, 'HiSparse PD requires mooncake'","typeGuard":"def hisparse_pd_supported(backend: str, model: str) -> bool:\n    return 'dsv4' not in model.lower() or backend == 'mooncake'","tryCatchPattern":null,"preventionTips":["Pin --disaggregation-transfer-backend mooncake for DSV4 deployments","Smoke-test new model + backend combos in staging before prod"],"tags":["disaggregation","hisparse","dsv4","mooncake","unsupported-backend"],"backgroundTag":"feature-not-supported-by-backend","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}