{"record":{"id":"fc3a09a7a7f8cb53","repo":"sgl-project/sglang","slug":"please-install-mooncake-by-following-the-instructi","errorCode":null,"errorMessage":"Please install mooncake by following the instructions at https://kvcache-ai.github.io/Mooncake/getting_started/build.html to run SGLang with MooncakeTransferEngine.","messagePattern":"Please install mooncake by following the instructions at https://kvcache-ai\\.github\\.io/Mooncake/getting_started/build\\.html to run SGLang with MooncakeTransferEngine\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"critical","filePath":"python/sglang/srt/distributed/device_communicators/mooncake_transfer_engine.py","lineNumber":121,"sourceCode":"    raise ValueError(\n        f\"No IB devices configured for GPU {gpu_id}. \"\n        f\"Available GPUs: {list(parsed_config.keys())}\"\n    )\n\n\nclass MooncakeTransferEngine:\n    \"\"\"Shared Mooncake transfer engine for RDMA/transfer operations.\"\"\"\n\n    def __init__(\n        self,\n        hostname: str,\n        gpu_id: Optional[int] = None,\n        ib_device: Optional[str] = None,\n    ):\n        try:\n            from mooncake.engine import TransferEngine\n        except ImportError as e:\n            raise ImportError(\n                \"Please install mooncake by following the instructions at \"\n                \"https://kvcache-ai.github.io/Mooncake/getting_started/build.html \"\n                \"to run SGLang with MooncakeTransferEngine.\"\n            ) from e\n\n        self.engine = TransferEngine()\n        self.hostname = hostname\n        self.gpu_id = gpu_id if gpu_id is not None else 0\n        # MC_FORCE_TCP=1 makes mooncake install TcpTransport instead of RDMA,\n        # in which case RDMA HCA selection is irrelevant; pass empty device.\n        if os.environ.get(\"MC_FORCE_TCP\") == \"1\":\n            self.ib_device = \"\"\n        else:\n            self.ib_device = get_ib_devices_for_gpu(ib_device, self.gpu_id)\n\n        self.initialize(\n            hostname=self.hostname,\n            device_name=self.ib_device,","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/distributed/device_communicators/mooncake_transfer_engine.py#L103-L139","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\npython -m sglang.launch_server --model ... --kv-transfer-engine mooncake\n# ImportError: Please install mooncake ...\n\n# after\npip install mooncake-transfer-engine --upgrade\npython -c 'from mooncake.engine import TransferEngine'  # sanity check\npython -m sglang.launch_server --model ... --kv-transfer-engine mooncake","handlingStrategy":"validation","validationCode":"def has_mooncake() -> bool:\n    try:\n        from mooncake.engine import TransferEngine  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\n# before constructing MooncakeTransferEngine:\nassert has_mooncake(), 'install mooncake-transfer-engine first'","typeGuard":null,"tryCatchPattern":"try:\n    engine = MooncakeTransferEngine(...)\nexcept ImportError as e:\n    if 'mooncake' in str(e):\n        raise SystemExit('mooncake missing; run pip install mooncake-transfer-engine') from e\n    raise","preventionTips":["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"],"tags":["mooncake","dependency","import-error","kv-cache-transfer","sglang"],"backgroundTag":"missing-python-dependency","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}