vllm-project/vllm · error · ValueError

layerwise MLA connector is not supported yet

Error message

layerwise MLA connector is not supported yet

What it means

ValueError from LMCache v1 adapter GPU-connector selection: the model uses MLA and the LMCache config also enables use_layerwise. Neither VLLMPagedMemLayerwiseGPUConnector nor the layerwise blending path supports MLA's latent KV layout, so the combination is rejected up front instead of failing during transfer. Fix by disabling one of the two options.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/lmcache_integration/vllm_v1_adapter.py:508

    metadata = LMCacheEngineMetadata(
        model_config.model,
        parallel_config.world_size,
        parallel_config.rank,
        "vllm",
        kv_dtype,
        kv_shape,
        use_mla,
    )

    use_gpu = need_gpu_interim_buffer(lmcache_config)
    vllm_gpu_connector: (
        VLLMBufferLayerwiseGPUConnector
        | VLLMPagedMemGPUConnectorV2
        | VLLMPagedMemLayerwiseGPUConnector
    )

    if use_mla and lmcache_config.use_layerwise:
        raise ValueError("layerwise MLA connector is not supported yet")

    # When use_mla is True, num_kv_head is 1
    hidden_dim_size = num_kv_head * head_size
    if lmcache_config.use_layerwise:
        if lmcache_config.enable_blending:
            # Use layerwise connector for blending
            vllm_gpu_connector = VLLMBufferLayerwiseGPUConnector(
                hidden_dim_size,
                num_layer,
                use_gpu=use_gpu,
                chunk_size=chunk_size,
                dtype=kv_dtype,
                device=device,
            )
        else:
            vllm_gpu_connector = VLLMPagedMemLayerwiseGPUConnector(
                hidden_dim_size,
                num_layer,

View on GitHub (pinned to c794754062)

Solutions

1. Set use_layerwise=False in the LMCache configuration when running MLA models.
2. If layerwise transfer is a hard requirement, use a non-MLA model until LMCache adds an MLA layerwise connector.
3. Watch LMCache release notes — this is an explicit 'not supported yet' guard that may be lifted later.

Example fix

# before
LMCacheEngineConfig(..., use_layerwise=True)
# after
LMCacheEngineConfig(..., use_layerwise=False)

if mla_enabled(model_config) and lmcache_config.use_layerwise:
    raise SystemExit("MLA + layerwise unsupported; set use_layerwise=False")  # fail at config time

When it happens

Trigger: Enabling lmcache config use_layerwise=true on an MLA model (DeepSeek family); also fires when enable_blending is combined with layerwise on MLA since that path selects the same unsupported layerwise connector.

Common situations: Tuning LMCache for layer-wise KV push/pop on DeepSeek-style models; configs copied from non-MLA deployments that used layerwise transfers.

Related errors

• MLA only works with naive serde mode..
• Either vllm_config must be provided, or all of model_config,
• LMCacheMPConnector only works without hybrid kv cache manage
• Unknown KVConnectorRole: {self.role}
• --use-replayssm is incompatible with KV connectors (P/D disa

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