{"record":{"id":"c48e03a61760a097","repo":"vllm-project/vllm","slug":"mooncake-is-not-available","errorCode":null,"errorMessage":"Mooncake is not available","messagePattern":"Mooncake is not available","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/mooncake/mooncake_connector.py","lineNumber":906,"sourceCode":"                request,\n                self.get_sw_clipped_blocks(block_ids),\n            )\n\n        return delay_free_blocks, None\n\n\nclass MooncakeConnectorWorker:\n    \"\"\"Implementation of Worker side methods\"\"\"\n\n    def __init__(\n        self,\n        vllm_config: VllmConfig,\n        engine_id: str,\n        kv_cache_config: \"KVCacheConfig\",\n    ):\n        if TransferEngine is None:\n            logger.error(\"Mooncake is not available\")\n            raise RuntimeError(\"Mooncake is not available\")\n        logger.info(\"Initializing Mooncake Transfer Engine worker %s\", engine_id)\n\n        self.vllm_config = vllm_config\n        # Capture device BEFORE TransferEngine init — MNNVL's NVLink allocator\n        # may change the current CUDA device during engine.initialize().\n        self.device_id = torch.accelerator.current_device_index()\n        current_platform.set_device(self.device_id)\n\n        self.engine = TransferEngine()\n        self.hostname = get_ip()\n\n        assert (kv_transfer_config := vllm_config.kv_transfer_config)\n        self.is_kv_producer: bool = kv_transfer_config.kv_role == \"kv_producer\"\n        self.is_kv_consumer: bool = kv_transfer_config.kv_role == \"kv_consumer\"\n        self.num_sender_workers = kv_transfer_config.kv_connector_extra_config.get(\n            \"num_workers\", 10\n        )\n        # Create more tasks than workers to keep the thread pool saturated.","sourceCodeStart":888,"sourceCodeEnd":924,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/mooncake/mooncake_connector.py#L888-L924","documentation":"RuntimeError raised in MooncakeConnectorWorker.__init__ when the mooncake TransferEngine symbol is None, i.e. the mooncake-engine package failed to import at module load (the import is guarded, usually with a log at import time). The worker cannot do RDMA/transfer-based KV transfer without the native engine, so it aborts during connector construction. Root cause is almost always a missing or broken mooncake-engine installation.","triggerScenarios":"Configuring kv_transfer_config with MooncakeTransferEngineConnector / MooncakeStoreConnector without mooncake-engine installed; mooncake-engine installed for a different Python version or with a broken native .so; CPU-only environment where the wheel's CUDA deps are absent.","commonSituations":"Fresh deployment forgetting the mooncake extra (e.g. pip install vllm[mooncake] or pip install mooncake-engine); upgrade that broke the native extension; container images lacking the RDMA libraries mooncake-engine links against.","solutions":["Install the mooncake engine package matching your environment (e.g. 'pip install mooncake-engine' or the vllm mooncake extra).","Verify import works directly: python -c 'from mooncake.engine import TransferEngine' and read the ImportError if it fails.","Ensure required native RDMA libraries (ibverbs, etc.) are present in the container/host image.","Confirm the mooncake-engine Python version matches the vLLM venv."],"exampleFix":"# before\n# (mooncake-engine not installed) -> RuntimeError at worker init\n# after\npip install mooncake-engine  # or: pip install 'vllm[mooncake]'","handlingStrategy":"validation","validationCode":"def mooncake_available() -> bool:\n    try:\n        from mooncake.engine import TransferEngine  # noqa: F401\n        return True\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Add mooncake-engine to the deployment image / requirements when using Mooncake connectors","Run a startup import check before configuring MooncakeTransferEngineConnector","Verify the native .so loads in the target container, not just on the build host"],"tags":["mooncake","import-error","dependencies","rdma","kv-transfer"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}