vllm-project/vllm · critical · RuntimeError

No KV cache tensors were registered with Mooncake.

Error message

No KV cache tensors were registered with Mooncake.

What it means

RuntimeError raised during register_kv_caches when the loop over the worker's KV cache tensors collected zero unique storage pointers, i.e. there were no KV cache tensors to register with the Mooncake engine. Without registered memory, the transfer engine cannot serve or fetch KV blocks, so the worker refuses to continue. It usually indicates the connector was pointed at a worker/layer set where no KV cache tensors exist (all layers hydrated from another source, empty kv_caches list, or wrong worker role).

Source

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

                self.block_len_per_layer.append(block_len)
                self.kv_block_len_per_layer.append(kv_block_len)
                self.registered_layer_names.append(layer_name)
                self.registered_layer_indices.append(layer_index)
                self.registered_group_indices.append(
                    self._layer_group_indices[layer_name]
                )
                storage = cache.untyped_storage()
                storage_addr = storage.data_ptr()
                if storage_addr not in seen_storage_ptrs:
                    seen_storage_ptrs.add(storage_addr)
                    kv_data_ptrs.append(storage_addr)
                    kv_data_lens.append(storage.nbytes())

        self.kv_caches_base_addr = region_base_addresses
        self.seen_base_addresses = kv_data_ptrs

        if not kv_data_ptrs:
            raise RuntimeError("No KV cache tensors were registered with Mooncake.")

        ret_value = self.engine.batch_register_memory(kv_data_ptrs, kv_data_lens)
        if ret_value != 0:
            raise RuntimeError("Mooncake batch memory registration failed.")

        self.device_kv_caches = kv_caches
        logger.debug(
            "registered block_lens=%s kv_block_lens=%s",
            self.block_len_per_layer,
            self.kv_block_len_per_layer,
        )

        # No need to launch server for D node.
        if self.is_kv_consumer:
            return

        ready_event = threading.Event()
        asyncio.run_coroutine_threadsafe(

View on GitHub (pinned to c794754062)

Solutions

1. Verify the node's kv_role: nodes that hold no KV cache should not run the Mooncake worker registration path.
2. Log/dump the kv_caches argument to register_kv_caches and confirm per-layer tensors are present and non-empty.
3. Check vllm/mooncake connector version compatibility if the kv_caches contract recently changed.
4. For models with unusual cache layouts, confirm the mooncake connector supports them before deployment.

def has_kv_caches(kv_caches) -> bool:
    return bool(kv_caches) and any(
        t is not None and t.untyped_storage().nbytes() > 0
        for ts in (kv_caches.values() if isinstance(kv_caches, dict) else kv_caches)
        for t in (ts if isinstance(ts, list) else [ts])
    )

Catch RuntimeError at registration; verify kv_role assignment and whether this node should hold KV caches; skip Mooncake worker registration on cache-less nodes rather than crashing.

When it happens

Trigger: register_kv_caches called with an empty kv_caches mapping; KVConnector worker instantiated on a replica whose KV cache tensors were already consumed/renamed by another mechanism; is_kv_consumer path receiving no local caches; a model with zero KV-cache-holding layers routed to the mooncake worker.

Common situations: Misconfigured KV role assignment (kv_role) where a node that has no KV caches still runs the mooncake worker adapter; upstream changes in how kv_caches are passed to connectors; edge-case models (MLA/fully offloaded) exposing no per-layer cache tensors.

Related errors

• Worker with dp_rank={payload.dp_rank}, tp_rank={payload.tp_r
• Mooncake is not available
• Mooncake Transfer Engine initialization failed.
• 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/98a3261c08e74f18. Report an issue: GitHub.