{"record":{"id":"1124b861e0408d8a","repo":"vllm-project/vllm","slug":"please-install-mooncake-by-following-the-instructi","errorCode":null,"errorMessage":"Please install mooncake by following the instructions at https://github.com/kvcache-ai/Mooncake/blob/main/doc/en/build.md to run vLLM with MooncakeStoreConnector.","messagePattern":"Please install mooncake by following the instructions at https://github\\.com/kvcache-ai/Mooncake/blob/main/doc/en/build\\.md to run vLLM with MooncakeStoreConnector\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"critical","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/worker.py","lineNumber":1213,"sourceCode":"# Store Worker\n# ============================================================\n\n\nclass MooncakeStoreWorker:\n    \"\"\"Worker-side component for MooncakeStoreConnector.\"\"\"\n\n    def __init__(\n        self,\n        vllm_config: VllmConfig,\n        kv_cache_config: KVCacheConfig,\n    ):\n        try:\n            from mooncake.store import (  # type: ignore\n                MooncakeDistributedStore,\n                ReplicateConfig,\n            )\n        except ImportError as e:\n            raise ImportError(\n                \"Please install mooncake by following the instructions at \"\n                \"https://github.com/kvcache-ai/Mooncake/blob/main/doc/\"\n                \"en/build.md to run vLLM with MooncakeStoreConnector.\"\n            ) from e\n\n        model_config = vllm_config.model_config\n        parallel_config = vllm_config.parallel_config\n\n        self.dp_rank = parallel_config.data_parallel_index\n        self.tp_rank = get_tensor_model_parallel_rank()\n        self.tp_size = get_tensor_model_parallel_world_size()\n        self.pp_size = parallel_config.pipeline_parallel_size\n        self.pp_rank = (parallel_config.rank // self.tp_size) % self.pp_size\n\n        self.pcp_size = get_pcp_group().world_size\n        self.pcp_rank = get_pcp_group().rank_in_group if self.pcp_size > 1 else 0\n        self.dcp_size = get_dcp_group().world_size\n        self.dcp_rank = get_dcp_group().rank_in_group if self.dcp_size > 1 else 0","sourceCodeStart":1195,"sourceCodeEnd":1231,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/worker.py#L1195-L1231","documentation":"The store-side worker imports mooncake.store (MooncakeDistributedStore, ReplicateConfig) at construction; if the installed mooncake package lacks the store sub-module (or mooncake is not installed at all), vLLM raises ImportError pointing at Mooncake's build instructions. Note this is the store API, a newer addition than the transfer-engine API other connectors use.","triggerScenarios":"pip-installing only mooncake-transfer-engine (or an older mooncake without mooncake.store) and selecting kv_connector='MooncakeStoreConnector'.","commonSituations":"Environments provisioned for the older MooncakeTransferEngine/P2P connector; mooncake pip wheel lagging the store feature; version mismatch after upgrading vLLM past the version that introduced MooncakeStoreConnector.","solutions":["Install mooncake from source with the store component per https://github.com/kvcache-ai/Mooncake/blob/main/doc/en/build.md","Verify the import works first: python -c 'from mooncake.store import MooncakeDistributedStore'","If you do not need the standalone store, switch kv_connector to a connector matching the mooncake build you have (e.g. MooncakeTransferEngine-based P2P)"],"exampleFix":"# before: mooncake-transfer-engine only\n# python -c 'from mooncake.store import MooncakeDistributedStore'  -> ModuleNotFoundError\n\n# after: build mooncake with store support, then re-check\npip install -e /path/to/mooncake\npython -c 'from mooncake.store import MooncakeDistributedStore'  # ok","handlingStrategy":"validation","validationCode":"try:\n    from mooncake.store import MooncakeDistributedStore  # noqa: F401\nexcept ImportError:\n    raise SystemExit(\n        \"mooncake with store support required; build per \"\n        \"https://github.com/kvcache-ai/Mooncake/blob/main/doc/en/build.md\")","typeGuard":null,"tryCatchPattern":"try:\n    from mooncake.store import MooncakeDistributedStore\nexcept ImportError as e:\n    # fail fast with an actionable message or fall back to another connector\n    raise RuntimeError(\"install mooncake store support\") from e","preventionTips":["Bake the mooncake build into the serving image and smoke-test the import at build time","Distinguish connector choice: MooncakeStoreConnector needs mooncake.store, not just the transfer engine","Re-verify imports after upgrading vLLM or mooncake"],"tags":["mooncake","import-error","installation","kv-transfer"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}