sgl-project/sglang · critical · ImportError

Please install mooncake by following the instructions at…

Error message

Please install mooncake by following the instructions at https://kvcache-ai.github.io/Mooncake/getting_started/build.html to run SGLang with MooncakeTransferEngine.

What it means

SGLang's MooncakeTransferEngine wraps the mooncake-engine Python package for KV-cache transfer (e.g. in PD-disaggregation or HiCache mooncake backend). Its __init__ imports mooncake.engine.TransferEngine and re-raises ImportError with install instructions when the package is missing. The error means the mooncake transfer engine dependency is not installed in the current Python environment.

Solutions

Install mooncake per the linked docs (e.g. pip install mooncake-transfer-engine matching your CUDA version), then retry
Verify the import works in the same interpreter: python -c 'from mooncake.engine import TransferEngine'
If using a venv/conda env, confirm sglang and mooncake are installed in the same environment
If you don't need mooncake, remove/disable mooncake-related flags (transfer engine / HiCache backend) so the class is never constructed

Example fix

# before
python -m sglang.launch_server --model ... --kv-transfer-engine mooncake
# ImportError: Please install mooncake ...

# after
pip install mooncake-transfer-engine --upgrade
python -c 'from mooncake.engine import TransferEngine'  # sanity check
python -m sglang.launch_server --model ... --kv-transfer-engine mooncake

Defensive patterns

Strategy: validation

Validate before calling

def has_mooncake() -> bool:
    try:
        from mooncake.engine import TransferEngine  # noqa: F401
        return True
    except ImportError:
        return False

# before constructing MooncakeTransferEngine:
assert has_mooncake(), 'install mooncake-transfer-engine first'

Try / catch

try:
    engine = MooncakeTransferEngine(...)
except ImportError as e:
    if 'mooncake' in str(e):
        raise SystemExit('mooncake missing; run pip install mooncake-transfer-engine') from e
    raise

Prevention

Pre-flight check 'from mooncake.engine import TransferEngine' in the serving environment
Pin mooncake-transfer-engine in the same requirements/env as sglang
Gate mooncake-only launch flags on an install check

When it happens

Trigger: Instantiating MooncakeTransferEngine (directly or by launching a server with --transfer-engine mooncake / a mooncake-based KV backend, or initializing the shared mooncake engine for elastic EP) when 'import mooncake.engine' fails because the mooncake/mooncake-transfer-engine package is absent or broken.

Common situations: Enabling KV-cache transfer engine = mooncake or mooncake-based HiCache/PD-disaggregation without installing mooncake; installing mooncake into a different conda/venv than the one running sglang; a partially installed/corrupted wheel; CPU-only or unsupported CUDA wheel causing import failure inside the package.

Related errors

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

Appendix: source

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

    raise ValueError(
        f"No IB devices configured for GPU {gpu_id}. "
        f"Available GPUs: {list(parsed_config.keys())}"
    )


class MooncakeTransferEngine:
    """Shared Mooncake transfer engine for RDMA/transfer operations."""

    def __init__(
        self,
        hostname: str,
        gpu_id: Optional[int] = None,
        ib_device: Optional[str] = None,
    ):
        try:
            from mooncake.engine import TransferEngine
        except ImportError as e:
            raise ImportError(
                "Please install mooncake by following the instructions at "
                "https://kvcache-ai.github.io/Mooncake/getting_started/build.html "
                "to run SGLang with MooncakeTransferEngine."
            ) from e

        self.engine = TransferEngine()
        self.hostname = hostname
        self.gpu_id = gpu_id if gpu_id is not None else 0
        # MC_FORCE_TCP=1 makes mooncake install TcpTransport instead of RDMA,
        # in which case RDMA HCA selection is irrelevant; pass empty device.
        if os.environ.get("MC_FORCE_TCP") == "1":
            self.ib_device = ""
        else:
            self.ib_device = get_ib_devices_for_gpu(ib_device, self.gpu_id)

        self.initialize(
            hostname=self.hostname,
            device_name=self.ib_device,

View on GitHub (pinned to 0132848349)