sgl-project/sglang · critical · ImportError

Please install mooncake by following the instructions at htt

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.

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)

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.