{"record":{"id":"44e9b099c17fc6a5","repo":"sgl-project/sglang","slug":"kvtransfererror","errorCode":null,"errorMessage":"KVTransferError","messagePattern":"KVTransferError","errorType":"exception","errorClass":"KVTransferError","httpStatus":null,"severity":"critical","filePath":"python/sglang/srt/disaggregation/mooncake/conn.py","lineNumber":2256,"sourceCode":"    state, then raise with the recorded reason -- or, when no reason was\n    recorded locally, report it as propagated from another rank. Expects the\n    concrete class to provide ``conclude_state``, ``clear()``,\n    ``bootstrap_room`` and ``kv_mgr``.\n    \"\"\"\n\n    def failure_exception(self):\n        # A room with no locally recorded reason failed on another rank.\n        if self.conclude_state is None:\n            self.conclude_state = KVPoll.Failed\n\n        self.clear()\n\n        with self.kv_mgr.failure_lock:\n            failure_reason = self.kv_mgr.failure_records.pop(self.bootstrap_room, None)\n        is_propagated = failure_reason is None\n        if is_propagated:\n            failure_reason = \"Failed due to an unknown reason from another rank\"\n        raise KVTransferError(\n            self.bootstrap_room, failure_reason, is_from_another_rank=is_propagated\n        )\n\n\nclass MooncakeKVSender(MooncakeFailureExceptionMixin, CommonKVSender):\n\n    def __init__(\n        self,\n        mgr: MooncakeKVManager,\n        bootstrap_addr: str,\n        bootstrap_room: int,\n        dest_tp_ranks: List[int],\n        pp_rank: int,\n        req_has_disagg_prefill_dp_rank: bool = False,\n    ):\n        super().__init__(\n            mgr,\n            bootstrap_addr,","sourceCodeStart":2238,"sourceCodeEnd":2274,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/disaggregation/mooncake/conn.py#L2238-L2274","documentation":"failure_exception raises KVTransferError carrying the bootstrap_room and the recorded failure reason; if this rank has no record the reason is propagated from another rank. It converts silent KV-transfer corruption into an explicit per-room failure.","triggerScenarios":"A transfer failure recorded against the bootstrap room (any rank failure) and later surfaced via failure_exception on the sender/receiver.","commonSituations":"One rank of a multi-TP PD transfer failing, causing all sibling rooms to fail with propagated reasons; surfaced during polling of transfer status.","solutions":["Inspect KVTransferError.failure_reason and the originating rank's logs for the true failure","Fix the root cause (fabric, registration, layout) — this error is the reporting channel, not the bug","Retry the request once the PD pair is healthy"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"def is_kv_transfer_error(e: BaseException) -> bool:\n    return type(e).__name__ == \"KVTransferError\"","tryCatchPattern":"try: ... except KVTransferError as e: log(e.failure_reason, e.is_from_another_rank); fail/retry the request's room, not the server","preventionTips":["Poll transfer status and surface KVTransferError per room","Correlate propagated failures back to the originating rank's logs"],"tags":["pd-disagg","kv-transfer","error-propagation"],"backgroundTag":"distributed-transfer-failed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}