sgl-project/sglang · error · RuntimeError

Mooncake's batch transfer requires mooncake-transfer-engine

Error message

Mooncake's batch transfer requires mooncake-transfer-engine >= 0.3.4.post2. Please upgrade Mooncake by 'pip install mooncake-transfer-engine --upgrade'

What it means

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.

Source

Thrown at python/sglang/srt/distributed/device_communicators/mooncake_transfer_engine.py:256

        return ret

    def batch_transfer_sync(
        self,
        session_id: str,
        buffers: List[int],
        peer_buffer_addresses: List[int],
        lengths: List[int],
    ) -> int:
        """Synchronously transfer data to the specified addresses in batches."""
        try:
            ret = self.engine.batch_transfer_sync_write(
                session_id, buffers, peer_buffer_addresses, lengths
            )
        except Exception:
            ret = -1
            if not hasattr(self.engine, "batch_transfer_sync_write"):
                raise RuntimeError(
                    "Mooncake's batch transfer requires mooncake-transfer-engine "
                    ">= 0.3.4.post2. Please upgrade Mooncake by "
                    "'pip install mooncake-transfer-engine --upgrade'"
                )

        if ret < 0:
            logger.debug(
                "Failed to batch transfer data. Buffers: %s, Session: %s, "
                "Peer addresses: %s",
                buffers,
                session_id,
                peer_buffer_addresses,
            )
        return ret

    def get_session_id(self):
        return self.session_id

View on GitHub (pinned to 0132848349)

Solutions

1. pip install mooncake-transfer-engine --upgrade (to >= 0.3.4.post2)
2. Verify: python -c "from mooncake.engine import TransferEngine; print(hasattr(TransferEngine, 'batch_transfer_sync_write'))"
3. Ensure all nodes in the cluster run the same upgraded mooncake version

Example fix

# before
pip install mooncake-transfer-engine==0.3.3  # later: RuntimeError on batch_transfer_sync

# after
pip install mooncake-transfer-engine>=0.3.4.post2 --upgrade

from mooncake.engine import TransferEngine
if not hasattr(TransferEngine, 'batch_transfer_sync_write'):
    raise RuntimeError('need mooncake-transfer-engine >= 0.3.4.post2')

try:
    mc.batch_transfer_sync(...)
except RuntimeError as e:
    if '0.3.4.post2' in str(e):
        raise SystemExit('pip install mooncake-transfer-engine --upgrade') from e
    raise

When it happens

Trigger: Calling batch_transfer_sync (public) with mooncake-transfer-engine < 0.3.4.post2 installed, where TransferEngine has no batch_transfer_sync_write attribute.

Common situations: 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.

Related errors

• Mooncake's batch register requires a newer version of moonca
• Failed to import 'set_transfer_engine' from 'mooncake.pg'. P
• Serve backend {name!r} uses API version {backend.api_version
• Kimi-K3 DCP with decode_attention_backend='cutedsl_mla' requ
• SGLANG_DISAGG_STAGING_BUFFER with pp_size > 1 is only suppor

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/7d5a2b6f6341e509. Report an issue: GitHub.