vllm-project/vllm · critical · ImportError

Please install mooncake by following the instructions at htt

Error message

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.

What it means

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.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/worker.py:1213

# Store Worker
# ============================================================


class MooncakeStoreWorker:
    """Worker-side component for MooncakeStoreConnector."""

    def __init__(
        self,
        vllm_config: VllmConfig,
        kv_cache_config: KVCacheConfig,
    ):
        try:
            from mooncake.store import (  # type: ignore
                MooncakeDistributedStore,
                ReplicateConfig,
            )
        except ImportError as e:
            raise ImportError(
                "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."
            ) from e

        model_config = vllm_config.model_config
        parallel_config = vllm_config.parallel_config

        self.dp_rank = parallel_config.data_parallel_index
        self.tp_rank = get_tensor_model_parallel_rank()
        self.tp_size = get_tensor_model_parallel_world_size()
        self.pp_size = parallel_config.pipeline_parallel_size
        self.pp_rank = (parallel_config.rank // self.tp_size) % self.pp_size

        self.pcp_size = get_pcp_group().world_size
        self.pcp_rank = get_pcp_group().rank_in_group if self.pcp_size > 1 else 0
        self.dcp_size = get_dcp_group().world_size
        self.dcp_rank = get_dcp_group().rank_in_group if self.dcp_size > 1 else 0

View on GitHub (pinned to c794754062)

Solutions

1. Install mooncake from source with the store component per https://github.com/kvcache-ai/Mooncake/blob/main/doc/en/build.md
2. Verify the import works first: python -c 'from mooncake.store import MooncakeDistributedStore'
3. 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)

Example fix

# before: mooncake-transfer-engine only
# python -c 'from mooncake.store import MooncakeDistributedStore'  -> ModuleNotFoundError

# after: build mooncake with store support, then re-check
pip install -e /path/to/mooncake
python -c 'from mooncake.store import MooncakeDistributedStore'  # ok

try:
    from mooncake.store import MooncakeDistributedStore  # noqa: F401
except ImportError:
    raise SystemExit(
        "mooncake with store support required; build per "
        "https://github.com/kvcache-ai/Mooncake/blob/main/doc/en/build.md")

try:
    from mooncake.store import MooncakeDistributedStore
except ImportError as e:
    # fail fast with an actionable message or fall back to another connector
    raise RuntimeError("install mooncake store support") from e

When it happens

Trigger: pip-installing only mooncake-transfer-engine (or an older mooncake without mooncake.store) and selecting kv_connector='MooncakeStoreConnector'.

Common situations: 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.

Related errors

• Mooncake is not available
• Mooncake Transfer Engine initialization failed.
• No KV cache tensors were registered with Mooncake.
• Mooncake batch memory registration failed.
• Engine ID mismatch for dp_rank={payload.dp_rank}: expected {

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/1124b861e0408d8a. Report an issue: GitHub.