{"record":{"id":"d370db0806ac0656","repo":"vllm-project/vllm","slug":"layerwise-mla-connector-is-not-supported-yet","errorCode":null,"errorMessage":"layerwise MLA connector is not supported yet","messagePattern":"layerwise MLA connector is not supported yet","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/lmcache_integration/vllm_v1_adapter.py","lineNumber":508,"sourceCode":"    metadata = LMCacheEngineMetadata(\n        model_config.model,\n        parallel_config.world_size,\n        parallel_config.rank,\n        \"vllm\",\n        kv_dtype,\n        kv_shape,\n        use_mla,\n    )\n\n    use_gpu = need_gpu_interim_buffer(lmcache_config)\n    vllm_gpu_connector: (\n        VLLMBufferLayerwiseGPUConnector\n        | VLLMPagedMemGPUConnectorV2\n        | VLLMPagedMemLayerwiseGPUConnector\n    )\n\n    if use_mla and lmcache_config.use_layerwise:\n        raise ValueError(\"layerwise MLA connector is not supported yet\")\n\n    # When use_mla is True, num_kv_head is 1\n    hidden_dim_size = num_kv_head * head_size\n    if lmcache_config.use_layerwise:\n        if lmcache_config.enable_blending:\n            # Use layerwise connector for blending\n            vllm_gpu_connector = VLLMBufferLayerwiseGPUConnector(\n                hidden_dim_size,\n                num_layer,\n                use_gpu=use_gpu,\n                chunk_size=chunk_size,\n                dtype=kv_dtype,\n                device=device,\n            )\n        else:\n            vllm_gpu_connector = VLLMPagedMemLayerwiseGPUConnector(\n                hidden_dim_size,\n                num_layer,","sourceCodeStart":490,"sourceCodeEnd":526,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/lmcache_integration/vllm_v1_adapter.py#L490-L526","documentation":"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.","triggerScenarios":"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.","commonSituations":"Tuning LMCache for layer-wise KV push/pop on DeepSeek-style models; configs copied from non-MLA deployments that used layerwise transfers.","solutions":["Set use_layerwise=False in the LMCache configuration when running MLA models.","If layerwise transfer is a hard requirement, use a non-MLA model until LMCache adds an MLA layerwise connector.","Watch LMCache release notes — this is an explicit 'not supported yet' guard that may be lifted later."],"exampleFix":"# before\nLMCacheEngineConfig(..., use_layerwise=True)\n# after\nLMCacheEngineConfig(..., use_layerwise=False)","handlingStrategy":"validation","validationCode":"if mla_enabled(model_config) and lmcache_config.use_layerwise:\n    raise SystemExit(\"MLA + layerwise unsupported; set use_layerwise=False\")  # fail at config time","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Add a config lint step that rejects use_layerwise for MLA models","Track LMCache release notes for MLA layerwise support"],"tags":["lmcache","mla","layerwise","config","kv-transfer"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}