{"record":{"id":"26463008a9e86cb7","repo":"sgl-project/sglang","slug":"nixl-kv-transfer-has-no-kv-memory-segments","errorCode":null,"errorMessage":"NIXL KV transfer has no KV memory segments","messagePattern":"NIXL KV transfer has no KV memory segments","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/disaggregation/nixl/conn.py","lineNumber":1017,"sourceCode":"            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\n            # Build the shared src dlist on the first equal-TP/MLA peer; later\n            # peers reuse it. Skipped entirely on heterogeneous-TP-only setups.\n            if \"\" not in self.prep_handles:\n                self._init_equal_tp_prep_handle(\n                    \"\",\n                    self.kv_args.kv_data_ptrs,\n                    self.kv_args.gpu_id,\n                    mem_kind=src_mem_kind,","sourceCodeStart":999,"sourceCodeEnd":1035,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/disaggregation/nixl/conn.py#L999-L1035","documentation":"Raised when _kv_xfer_mem_segments returns an empty list, meaning no valid source/destination memory-kind pairing exists for the mixed-memory (HiSparse) equal-TP/MLA transfer path. The destination KV memory kinds are heterogeneous but none of the supported src-kind/dst-kind segment combinations match, so there are no transferable KV segments.","triggerScenarios":"Equal-TP or MLA/hybrid-MLA backend where _homogeneous_kv_mem_kind raises NotImplementedError (mixed dst mem kinds), decode_only_spec_dec is False, and _kv_xfer_mem_segments(self.kv_args.kv_data_mem_kinds, peer_info.dst_kv_mem_kinds) yields no segments — e.g. a source memory kind with no compatible destination segment.","commonSituations":"Mismatched hierarchical-cache configurations between prefill and decode nodes (one VRAM-only, the other with a DRAM tier); version drift where one side reports mem kinds the other cannot pair.","solutions":["Make prefill and decode use the same KV cache memory configuration (both VRAM-only or both hierarchical with the same layout)","Check kv_data_mem_kinds on both sides at startup and align server args (--enable-hierarchical-cache, hi-cache ratio settings)","Update both PD nodes to the same SGLang version so mem-kind negotiation matches","If hierarchical cache is not needed, disable it on both sides"],"exampleFix":"# before\nprefill:  --enable-hierarchical-cache --hicache-ratio 2.0\ndecode:   (no hicache)\n# after\nprefill:  --enable-hierarchical-cache --hicache-ratio 2.0\ndecode:   --enable-hierarchical-cache --hicache-ratio 2.0","handlingStrategy":"validation","validationCode":"from sglang.srt.disaggregation.nixl.conn import _kv_xfer_mem_segments\nassert len(_kv_xfer_mem_segments(src.kv_data_mem_kinds, dst.kv_data_mem_kinds)) > 0, 'no transferable KV segments'","typeGuard":null,"tryCatchPattern":"except ValueError as e:\n    if 'no KV memory segments' in str(e):\n        fail_cluster_preflight('misaligned hicache configs between prefill and decode')","preventionTips":["Run PD clusters with identical hicache settings on both roles","Assert matching kv_data_mem_kinds at registration time in test rigs","Pin both nodes to the same SGLang version"],"tags":["nixl","disaggregation","hicache","memory-registration","pd-disaggregation"],"backgroundTag":"memory-kind-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}