{"record":{"id":"98a3261c08e74f18","repo":"vllm-project/vllm","slug":"no-kv-cache-tensors-were-registered-with-mooncake","errorCode":null,"errorMessage":"No KV cache tensors were registered with Mooncake.","messagePattern":"No KV cache tensors were registered with Mooncake\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/mooncake/mooncake_connector.py","lineNumber":1723,"sourceCode":"                self.block_len_per_layer.append(block_len)\n                self.kv_block_len_per_layer.append(kv_block_len)\n                self.registered_layer_names.append(layer_name)\n                self.registered_layer_indices.append(layer_index)\n                self.registered_group_indices.append(\n                    self._layer_group_indices[layer_name]\n                )\n                storage = cache.untyped_storage()\n                storage_addr = storage.data_ptr()\n                if storage_addr not in seen_storage_ptrs:\n                    seen_storage_ptrs.add(storage_addr)\n                    kv_data_ptrs.append(storage_addr)\n                    kv_data_lens.append(storage.nbytes())\n\n        self.kv_caches_base_addr = region_base_addresses\n        self.seen_base_addresses = kv_data_ptrs\n\n        if not kv_data_ptrs:\n            raise RuntimeError(\"No KV cache tensors were registered with Mooncake.\")\n\n        ret_value = self.engine.batch_register_memory(kv_data_ptrs, kv_data_lens)\n        if ret_value != 0:\n            raise RuntimeError(\"Mooncake batch memory registration failed.\")\n\n        self.device_kv_caches = kv_caches\n        logger.debug(\n            \"registered block_lens=%s kv_block_lens=%s\",\n            self.block_len_per_layer,\n            self.kv_block_len_per_layer,\n        )\n\n        # No need to launch server for D node.\n        if self.is_kv_consumer:\n            return\n\n        ready_event = threading.Event()\n        asyncio.run_coroutine_threadsafe(","sourceCodeStart":1705,"sourceCodeEnd":1741,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/mooncake/mooncake_connector.py#L1705-L1741","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the node's kv_role: nodes that hold no KV cache should not run the Mooncake worker registration path.","Log/dump the kv_caches argument to register_kv_caches and confirm per-layer tensors are present and non-empty.","Check vllm/mooncake connector version compatibility if the kv_caches contract recently changed.","For models with unusual cache layouts, confirm the mooncake connector supports them before deployment."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"def has_kv_caches(kv_caches) -> bool:\n    return bool(kv_caches) and any(\n        t is not None and t.untyped_storage().nbytes() > 0\n        for ts in (kv_caches.values() if isinstance(kv_caches, dict) else kv_caches)\n        for t in (ts if isinstance(ts, list) else [ts])\n    )","typeGuard":null,"tryCatchPattern":"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.","preventionTips":["Map kv_role per node deliberately in the deployment config","Log the kv_caches inventory before registration in debug builds","Test the full topology (producer/consumer) in staging before production"],"tags":["mooncake","kv-cache","registration","kv-transfer"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}