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.

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)

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 Transfer Engine initialization failed.
• Mooncake batch memory registration failed.
• Please install mooncake by following the instructions at htt
• JSON error: {0}
• Tokenizer error: {0}

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