vllm-project/vllm · critical · RuntimeError

Mooncake is not available

Error message

Mooncake is not available

What it means

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.

Solutions

1. Install the mooncake engine package matching your environment (e.g. 'pip install mooncake-engine' or the vllm mooncake extra).
2. Verify import works directly: python -c 'from mooncake.engine import TransferEngine' and read the ImportError if it fails.
3. Ensure required native RDMA libraries (ibverbs, etc.) are present in the container/host image.
4. Confirm the mooncake-engine Python version matches the vLLM venv.

Example fix

# before
# (mooncake-engine not installed) -> RuntimeError at worker init
# after
pip install mooncake-engine  # or: pip install 'vllm[mooncake]'

def mooncake_available() -> bool:
    try:
        from mooncake.engine import TransferEngine  # noqa: F401
        return True
    except Exception:
        return False

When it happens

Trigger: 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.

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

Related errors

• Mooncake batch memory registration failed.
• Mooncake Transfer Engine initialization failed.
• Please install mooncake by following the instructions at…
• block_size ( ) must be a multiple of hash_block_size ( )
• embedded mode requires global_segment_size > 0

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

Appendix: source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/mooncake/mooncake_connector.py:906

                request,
                self.get_sw_clipped_blocks(block_ids),
            )

        return delay_free_blocks, None


class MooncakeConnectorWorker:
    """Implementation of Worker side methods"""

    def __init__(
        self,
        vllm_config: VllmConfig,
        engine_id: str,
        kv_cache_config: "KVCacheConfig",
    ):
        if TransferEngine is None:
            logger.error("Mooncake is not available")
            raise RuntimeError("Mooncake is not available")
        logger.info("Initializing Mooncake Transfer Engine worker %s", engine_id)

        self.vllm_config = vllm_config
        # Capture device BEFORE TransferEngine init — MNNVL's NVLink allocator
        # may change the current CUDA device during engine.initialize().
        self.device_id = torch.accelerator.current_device_index()
        current_platform.set_device(self.device_id)

        self.engine = TransferEngine()
        self.hostname = get_ip()

        assert (kv_transfer_config := vllm_config.kv_transfer_config)
        self.is_kv_producer: bool = kv_transfer_config.kv_role == "kv_producer"
        self.is_kv_consumer: bool = kv_transfer_config.kv_role == "kv_consumer"
        self.num_sender_workers = kv_transfer_config.kv_connector_extra_config.get(
            "num_workers", 10
        )
        # Create more tasks than workers to keep the thread pool saturated.

View on GitHub (pinned to c794754062)