vllm-project/vllm · error · RuntimeError

LMCacheMPConnector only works without hybrid kv cache manage

Error message

LMCacheMPConnector only works without hybrid kv cache manager. Please pass --disable-hybrid-kv-cache-manager when starting vllm

What it means

RuntimeError from reformat_block_ids in LMCacheMPConnector: the scheduler delivered a tuple of MORE than one block-id list, which is the format the hybrid KV cache manager uses (one list per cache 'slide'/allocator). The multi-process LMCache connector only understands a single flat block list, so vLLM must run with the hybrid KV cache manager disabled. Note the asymmetry: block_ids=None returns [] and a single-element tuple passes; only len>1 tuples raise.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/lmcache_mp_connector.py:78

    from vllm.forward_context import ForwardContext
    from vllm.v1.core.kv_cache_manager import KVCacheBlocks
    from vllm.v1.core.kv_cache_utils import BlockHash
    from vllm.v1.kv_cache_interface import KVCacheConfig
    from vllm.v1.request import Request

logger = lmcache_init_logger(__name__)


# Helper functions
def reformat_block_ids(block_ids: tuple[list[int], ...] | None) -> list[int]:
    if block_ids is None:
        return []
    assert isinstance(block_ids, tuple), (
        f"Expected block_ids to be a tuple of lists, but got {type(block_ids)}"
    )

    if len(block_ids) > 1:
        raise RuntimeError(
            "LMCacheMPConnector only works without hybrid kv cache manager. "
            "Please pass --disable-hybrid-kv-cache-manager when starting vllm"
        )

    return block_ids[0]


def extract_world_size_and_kv_rank(
    world_size: int,
    rank: int,
    vllm_config: VllmConfig,
) -> tuple[int, int]:
    """
    Convert the rank for the MLA.
    """
    use_mla = mla_enabled(vllm_config.model_config)
    if not use_mla:
        return world_size, rank

View on GitHub (pinned to c794754062)

Solutions

Add --disable-hybrid-kv-cache-manager to the vLLM server/worker launch command, exactly as the message instructs.
Alternatively set the equivalent cache_config option in a programmatic launch (cache_config.disable_hybrid_kv_cache_manager = True).
Check LMCache release notes for when native hybrid-manager support lands if you need both features.

Example fix

# before
vllm serve model --kv-transfer-config lmcache_mp_config
# after
vllm serve model --kv-transfer-config lmcache_mp_config --disable-hybrid-kv-cache-manager

Defensive patterns

Strategy: validation

Validate before calling

def validate_block_ids(block_ids):
    if isinstance(block_ids, tuple) and len(block_ids) > 1:
        raise RuntimeError("hybrid KV manager active; pass --disable-hybrid-kv-cache-manager")
    return list(block_ids[0]) if block_ids else []

Prevention

Always launch LMCacheMP deployments with --disable-hybrid-kv-cache-manager
Add the flag to deployment templates and CI smoke tests so upgrades cannot silently re-enable hybrid mode

When it happens

Trigger: Starting vLLM with the LMCacheMPConnector (e.g. LMCacheMP, LMCacheMPGroup) while the hybrid KV cache manager is active, so block_ids arrives as (sliding_ids, full_ids); default behavior on vLLM versions where hybrid KV cache manager is on by default.

Common situations: Upgrading vLLM to a version that enables the hybrid KV cache manager by default while keeping an LMCacheMP deployment config unchanged; new LMCacheMP users missing the required flag.

Related errors

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