{"record":{"id":"7d5a2b6f6341e509","repo":"sgl-project/sglang","slug":"mooncake-s-batch-transfer-requires-mooncake-transf","errorCode":null,"errorMessage":"Mooncake's batch transfer requires mooncake-transfer-engine >= 0.3.4.post2. Please upgrade Mooncake by 'pip install mooncake-transfer-engine --upgrade'","messagePattern":"Mooncake's batch transfer requires mooncake-transfer-engine >= 0\\.3\\.4\\.post2\\. Please upgrade Mooncake by 'pip install mooncake-transfer-engine --upgrade'","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/distributed/device_communicators/mooncake_transfer_engine.py","lineNumber":256,"sourceCode":"\n        return ret\n\n    def batch_transfer_sync(\n        self,\n        session_id: str,\n        buffers: List[int],\n        peer_buffer_addresses: List[int],\n        lengths: List[int],\n    ) -> int:\n        \"\"\"Synchronously transfer data to the specified addresses in batches.\"\"\"\n        try:\n            ret = self.engine.batch_transfer_sync_write(\n                session_id, buffers, peer_buffer_addresses, lengths\n            )\n        except Exception:\n            ret = -1\n            if not hasattr(self.engine, \"batch_transfer_sync_write\"):\n                raise RuntimeError(\n                    \"Mooncake's batch transfer requires mooncake-transfer-engine \"\n                    \">= 0.3.4.post2. Please upgrade Mooncake by \"\n                    \"'pip install mooncake-transfer-engine --upgrade'\"\n                )\n\n        if ret < 0:\n            logger.debug(\n                \"Failed to batch transfer data. Buffers: %s, Session: %s, \"\n                \"Peer addresses: %s\",\n                buffers,\n                session_id,\n                peer_buffer_addresses,\n            )\n        return ret\n\n    def get_session_id(self):\n        return self.session_id\n","sourceCodeStart":238,"sourceCodeEnd":274,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/distributed/device_communicators/mooncake_transfer_engine.py#L238-L274","documentation":"MooncakeTransferEngine.batch_transfer_sync calls engine.batch_transfer_sync_write for batched synchronous writes; the AttributeError from an engine older than 0.3.4.post2 (which lacks that method) is caught and converted to a RuntimeError requesting an upgrade. Other failures just set ret=-1 and fall through.","triggerScenarios":"Calling batch_transfer_sync (public) with mooncake-transfer-engine < 0.3.4.post2 installed, where TransferEngine has no batch_transfer_sync_write attribute.","commonSituations":"Newer SGLang using batched transfers against an old pinned mooncake wheel in a Docker image; partial cluster upgrades; environments where mooncake was installed from source at an older commit.","solutions":["pip install mooncake-transfer-engine --upgrade (to >= 0.3.4.post2)","Verify: python -c \"from mooncake.engine import TransferEngine; print(hasattr(TransferEngine, 'batch_transfer_sync_write'))\"","Ensure all nodes in the cluster run the same upgraded mooncake version"],"exampleFix":"# before\npip install mooncake-transfer-engine==0.3.3  # later: RuntimeError on batch_transfer_sync\n\n# after\npip install mooncake-transfer-engine>=0.3.4.post2 --upgrade","handlingStrategy":"validation","validationCode":"from mooncake.engine import TransferEngine\nif not hasattr(TransferEngine, 'batch_transfer_sync_write'):\n    raise RuntimeError('need mooncake-transfer-engine >= 0.3.4.post2')","typeGuard":null,"tryCatchPattern":"try:\n    mc.batch_transfer_sync(...)\nexcept RuntimeError as e:\n    if '0.3.4.post2' in str(e):\n        raise SystemExit('pip install mooncake-transfer-engine --upgrade') from e\n    raise","preventionTips":["Pin mooncake-transfer-engine>=0.3.4.post2 in requirements","Feature-check batch_transfer_sync_write at startup","Keep mooncake versions uniform across cluster nodes"],"tags":["mooncake","version-mismatch","batch-transfer","upgrade-required","sglang"],"backgroundTag":"library-version-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}