{"record":{"id":"646718d59959b15b","repo":"vllm-project/vllm","slug":"mla-only-works-with-naive-serde-mode","errorCode":null,"errorMessage":"MLA only works with naive serde mode..","messagePattern":"MLA only works with naive serde mode\\.\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/lmcache_integration/vllm_v1_adapter.py","lineNumber":467,"sourceCode":"    if curr_engine := LMCacheEngineBuilder.get(ENGINE_NAME):\n        return curr_engine\n\n    model_config = vllm_config.model_config\n    parallel_config = vllm_config.parallel_config\n    cache_config = vllm_config.cache_config\n\n    assert isinstance(lmcache_config, LMCacheEngineConfig), (\n        \"LMCache v1 configuration is should be passed.\"\n    )\n\n    kv_dtype = get_kv_cache_torch_dtype(cache_config.cache_dtype, model_config.dtype)\n\n    use_mla = mla_enabled(model_config)\n    if use_mla and (\n        lmcache_config.remote_serde != \"naive\"\n        and lmcache_config.remote_serde is not None\n    ):\n        raise ValueError(\"MLA only works with naive serde mode..\")\n\n    # construct kv shape (for mem pool)\n    num_layer = model_config.get_num_layers(parallel_config)\n    num_mtp_layers = _calculate_mtp_layers(vllm_config, model_config)\n    num_layer += num_mtp_layers\n    chunk_size = lmcache_config.chunk_size\n    num_kv_head = model_config.get_num_kv_heads(parallel_config)\n    head_size = model_config.get_head_size()\n    kv_shape = (num_layer, 1 if use_mla else 2, chunk_size, num_kv_head, head_size)\n    logger.info(\n        \"use mla: %s, kv shape: %s, num_mtp_layers: %s\",\n        use_mla,\n        kv_shape,\n        num_mtp_layers,\n    )\n\n    # Change current device.\n    from vllm.distributed.parallel_state import get_world_group","sourceCodeStart":449,"sourceCodeEnd":485,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/lmcache_integration/vllm_v1_adapter.py#L449-L485","documentation":"ValueError from the LMCache v1 adapter setup: the model uses MLA (Multi-head Latent Attention, e.g. DeepSeek family) but the LMCache config sets remote_serde to a non-'naive' value. MLA stores a single latent KV tensor that cannot be safely re-serialized by the optimized/other serde backends, so only the naive serializer is permitted (None, which defaults to naive, is also allowed). This is a configuration conflict detected at connector construction time.","triggerScenarios":"Running an MLA model (DeepSeek-V2/V3 and derivatives) with lmcache config remote_serde set to e.g. 'cachegen' or 'fast'; passing an LMCacheEngineConfig built externally with remote_serde customized while model_config has MLA enabled.","commonSituations":"Copy-pasted LMCache config from a non-MLA deployment (Llama-style) onto a DeepSeek deployment; enabling cachegen/binary serde for bandwidth savings and hitting the MLA restriction.","solutions":["Set remote_serde to 'naive' (or leave it unset/None) in the LMCache configuration.","If you need the advanced serde modes, use a non-MLA model.","Verify model MLA status with mla_enabled(model_config) when unsure why the check fires."],"exampleFix":"# before\nLMCacheEngineConfig(..., remote_serde=\"cachegen\")\n# after\nLMCacheEngineConfig(..., remote_serde=\"naive\")","handlingStrategy":"validation","validationCode":"from vllm.config import ModelConfig\n# before building the engine:\nif mla_enabled(model_config) and cfg.remote_serde not in (None, \"naive\"):\n    cfg.remote_serde = \"naive\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate remote_serde against model family at config-load time","Keep MLA-model deployments on a dedicated, naive-serde LMCache config template"],"tags":["lmcache","mla","config","serde","kv-transfer"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}