{"record":{"id":"b774bfdff5235dcd","repo":"sgl-project/sglang","slug":"nixl-pd-transfer-does-not-support-hisparse-combine","errorCode":null,"errorMessage":"NIXL PD transfer does not support HiSparse combined with decode-only speculative decoding.","messagePattern":"NIXL PD transfer does not support HiSparse combined with decode-only speculative decoding\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/disaggregation/nixl/conn.py","lineNumber":1009,"sourceCode":"            peer_info.dst_homogeneous_mem_kind = dst_mem_kind\n            peer_info.dcp_token_item_lens = self.prepare_dcp_token_item_lens(\n                dst_kv_item_lens\n            )\n            return\n\n        if (\n            self.is_mla_backend\n            or self.is_hybrid_mla_backend\n            or peer_info.decode_tp_size == self.attn_tp_size\n        ):\n            dst_mem_kind = None\n            try:\n                dst_mem_kind = _homogeneous_kv_mem_kind(\n                    peer_info.dst_kv_mem_kinds, \"destination\"\n                )\n            except NotImplementedError:\n                if decode_only_spec_dec:\n                    raise NotImplementedError(\n                        \"NIXL PD transfer does not support HiSparse combined with \"\n                        \"decode-only speculative decoding.\"\n                    )\n                mem_segments = _kv_xfer_mem_segments(\n                    self.kv_args.kv_data_mem_kinds, peer_info.dst_kv_mem_kinds\n                )\n                if not mem_segments:\n                    raise ValueError(\"NIXL KV transfer has no KV memory segments\")\n                self._init_mixed_equal_tp_prep_handles(peer_info, mem_segments)\n                return\n\n            if decode_only_spec_dec and dst_mem_kind != \"VRAM\":\n                raise NotImplementedError(\n                    \"NIXL PD transfer does not support HiSparse combined with \"\n                    \"decode-only speculative decoding.\"\n                )\n\n            peer_info.dst_homogeneous_mem_kind = dst_mem_kind","sourceCodeStart":991,"sourceCodeEnd":1027,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/disaggregation/nixl/conn.py#L991-L1027","documentation":"Raised in _prepare_payload_xfer when the decode (destination) side registers a heterogeneous mix of KV memory kinds (VRAM + DRAM, i.e. HiSparse/hierarchical cache) AND the decode instance runs speculative decoding while prefill does not (n_dst > n_src, 'decode-only spec dec'). NIXL PD transfer cannot build descriptor lists for mixed-memory destinations with the extra speculative KV regions, so it refuses with NotImplementedError.","triggerScenarios":"Prefill node without speculative decoding + decode node with speculative decoding enabled, where decode's kv_data_mem_kinds mixes VRAM and DRAM (HiSparse/hierarchical KV cache enabled on decode), so _homogeneous_kv_mem_kind raises NotImplementedError for the destination and decode_only_spec_dec is True.","commonSituations":"Enabling --speculative-algorithm (e.g. EAGLE) only on the decode server of a PD-disaggregated cluster while also enabling hierarchical cache (HiCache/HiSparse with DRAM tier) on the decode side.","solutions":["Disable speculative decoding on the decode instance (align spec-dec config between prefill and decode)","Disable the hierarchical/HiSparse KV cache on the decode instance so all destination KV tensors are VRAM (homogeneous)","Run prefill with the same speculative decoding setup so n_dst == n_src (decode-only spec dec no longer triggers)","Upgrade SGLang once mixed-memory NIXL transfer with spec-dec support lands"],"exampleFix":"# before (decode server)\n--disaggregation decode --speculative-algorithm EAGLE --enable-hierarchical-cache\n# after\n--disaggregation decode --enable-hierarchical-cache   # no spec dec, or drop hi-cache","handlingStrategy":"validation","validationCode":"def preflight_check(src_args, dst_args):\n    mixed = len(set(dst_args.kv_data_mem_kinds)) > 1\n    spec_dec_mismatch = (src_args.speculative_algorithm is None\n                         and dst_args.speculative_algorithm is not None)\n    return not (mixed and spec_dec_mismatch)","typeGuard":null,"tryCatchPattern":"try:\n    conn.add_transfer_request(...)\nexcept NotImplementedError as e:\n    if 'HiSparse' in str(e):\n        logger.error('Disable spec-dec on decode or hicache; retrying without spec dec')\n    raise","preventionTips":["Keep speculative decoding config identical on prefill and decode nodes","Document which PD feature combinations (hicache x spec-dec x hetero-TP) are supported before rollout","Add a startup preflight comparing kv_data_mem_kinds and spec-dec flags across PD peers"],"tags":["nixl","disaggregation","speculative-decoding","hicache","pd-disaggregation"],"backgroundTag":"unsupported-feature-combination","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}